Pascal Super Library/Pascal Super Library (CW International)(1997).bin/GAME_UTL/PCGPE10/LIMEMS41.DOC

Text File | 1994-05-10 | 438.6 KB | 13,224 lines

          The associated file (LIMEMS41.DOC) is a complete transcription of
          the Lotus/Intel/Microsoft (LIM) Expanded Memory Specification
          (EMS) Version 4.0, updated October 1987.  It can be printed by
          "COPY LIMEMS41.DOC PRN:"

          I created this transcription because of the difficulty I origin-
          ally had finding a copy of the document, because of the number of
          people who have subsequently expressed an interest in having
          access to a machine-readable copy of the specification, and,
          finally, because of the annoying number of typographical errors
          contained in the original and updated documents.

          This transcription is not an exact letter-for-letter duplicate of
          the original document.  Some minor changes were necessitated by
          the simple fact that the document's proportionally-spaced, multi-
          fonted typography and line drawings did not lend themselves to
          the generic fixed-spacing, single-fonted, non-graphical ASCII
          transcription I wanted to produce for general dissemination.

          Other minor changes were made to correct obvious typographical
          and grammatical errors, or to simply improve the visual aes-
          thetics of the presented material.

          In one area, however, I simply trashed their original material
          and substituted my own.  This area is the Index.  The original
          document contains an Index that is little more than a reformatt-
          ing of the Table of Contents.  As anyone who has ever indexed a
          large document knows, it is very difficult to produce an Index
          that is both complete AND easy to use.  I didn't have time to
          produce one that was both, so I aimed for the former.  In fact,
          the Index I have provided is more of an alphabetical listing of
          key words and phrases and the pages where they are referenced,
          than it is a more typical Index with its multi-level headings and
          subheadings.

          You should be able obtain a printed, 3-hole-punched, 5.5 x 8.5"
          copy of the original (and uncorrected) document directly from
          Intel by calling their "Information Department" at 1-800-538-3373
          and asking for a copy of the "LIM EMS 4.0 Developer's Kit."  It
          is available free of charge and mine arrived in about two weeks.
          (European availability, however, is reported to be from poor to
          non-existent.)

          It is my intent to provide this transcription as a public
          service.  I am, therefore, releasing it into the public domain.
          The original document has also been released into the public
          domain by Lotus, Intel, and Microsoft, though it remains their
          copyrighted property (I'm not quite sure how they manage to do
          that).

          I have tried as best I can to provide an accurate and corrected
          transcription of the original document.  It is inevitable,
          however, that some typographical errors have slipped through in
          spite of my hours of bleary-eyed proof reading.  For these errors
          I apologize and plead simple human frailty.

               THIS TRANSCRIPTION IS PROVIDED WITHOUT ANY GUARANTEES
               OR WARRANTIES OF ANY KIND, AND I ASSUME ABSOLUTELY NO
               LIABILITY FOR ITS ACCURACY, CONTENT, OR SUBSEQUENT USE.

          Dick Flanagan, W6OLD, Ben Lomond, California        November 1987











                           LOTUS(R)/INTEL(R)/MICROSOFT(R)

                          EXPANDED MEMORY SPECIFICATION [1]












                                     Version 4.0
                                     300275-005
                                    October, 1987












          Copyright (C) 1987

          Lotus Development Corporation
          55 Cambridge Parkway
          Cambridge, MA  02142

          Intel Corporation
          5200 NE Elam Young Parkway
          Hillsboro, OR  97124

          Microsoft Corporation
          16011 NE 35th Way
          Box 97017
          Redmond, WA  98073


               [1] Transcribed into machine-readable form by Dick Flanagan,
          Ben Lomond, California.  This transcription is released into the
          public domain without warranty or assumption of liability.





               This specification was jointly developed by Lotus Develop-
               ment Corporation, Intel Corporation, and Microsoft Corpora-
               tion.  Although it has been released into the public domain
               and is not confidential or proprietary, the specification is
               still the copyright and property of Lotus Development
               Corporation, Intel Corporation, and Microsoft Corporation.


          DISCLAIMER OF WARRANTY

               LOTUS DEVELOPMENT CORPORATION, INTEL CORPORATION, AND MICRO-
               SOFT CORPORATION EXCLUDE ANY AND ALL IMPLIED WARRANTIES,
               INCLUDING WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
               PARTICULAR PURPOSE.  NEITHER LOTUS NOR INTEL NOR MICROSOFT
               MAKE ANY WARRANTY OF REPRESENTATION, EITHER EXPRESS OR
               IMPLIED, WITH RESPECT TO THIS SPECIFICATION, ITS QUALITY,
               PERFORMANCE, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR
               PURPOSE.  NEITHER LOTUS NOR INTEL NOR MICROSOFT SHALL HAVE
               ANY LIABILITY FOR SPECIAL, INCIDENTAL, OR CONSEQUENTIAL
               DAMAGES ARISING OUT OF OR RESULTING FROM THE USE OR MODIF-
               ICATION OF THIS SPECIFICATION.



          This specification uses the following trademarks:

          Intel is a trademark of Intel Corporation
          Lotus is a trademark of Lotus Development Corporation
          Microsoft is a trademark of Microsoft Corporation
























                                                                         ii





          CONTENTS



          Chapter 1
          INTRODUCTION
            What is Expanded Memory? . . . . . . . . . . . . . . . . .    1
            How Expanded Memory Works  . . . . . . . . . . . . . . . .    1

          Chapter 2
          WRITING PROGRAMS THAT USE EXPANDED MEMORY
            What Every Program Must Do . . . . . . . . . . . . . . . .    4
            Advanced Programming . . . . . . . . . . . . . . . . . . .    5
              Saving The State of Mapping Hardware . . . . . . . . . .    6
              Retrieving Handle and Page Counts  . . . . . . . . . . .    6
              Mapping and Unmapping Multiple Pages . . . . . . . . . .    6
              Reallocating Pages . . . . . . . . . . . . . . . . . . .    6
              Using Handles and Assigning Names to Handles . . . . . .    6
              Using Handle Attributes  . . . . . . . . . . . . . . . .    7
              Altering Page Maps and Jumping/Calling . . . . . . . . .    7
              Moving or Exchanging Memory Regions  . . . . . . . . . .    7
              Getting the Amount of Mappable Memory  . . . . . . . . .    8
              Operating System Functions . . . . . . . . . . . . . . .    8
            Programming Guidelines . . . . . . . . . . . . . . . . . .   12
            Examples . . . . . . . . . . . . . . . . . . . . . . . . .   14
              Example 1  . . . . . . . . . . . . . . . . . . . . . . .   14
              Example 2  . . . . . . . . . . . . . . . . . . . . . . .   19
              Example 3  . . . . . . . . . . . . . . . . . . . . . . .   30
              Example 4  . . . . . . . . . . . . . . . . . . . . . . .   32

          Chapter 3
          EMM FUNCTIONS
            Function 1. Get Status . . . . . . . . . . . . . . . . . .   37
            Function 2. Get Page Frame Address . . . . . . . . . . . .   38
            Function 3. Get Unallocated Page Count . . . . . . . . . .   40
            Function 4. Allocate Pages . . . . . . . . . . . . . . . .   42
            Function 5. Map/Unmap Handle Pages . . . . . . . . . . . .   46
            Function 6. Deallocate Pages . . . . . . . . . . . . . . .   49
            Function 7. Get Version  . . . . . . . . . . . . . . . . .   51
            Function 8. Save Page Map  . . . . . . . . . . . . . . . .   53
            Function 9. Restore Page Map . . . . . . . . . . . . . . .   55
            Function 10. Reserved  . . . . . . . . . . . . . . . . . .   57
            Function 11. Reserved  . . . . . . . . . . . . . . . . . .   58
            Function 12. Get Handle Count  . . . . . . . . . . . . . .   59
            Function 13. Get Handle Pages  . . . . . . . . . . . . . .   61
            Function 14. Get All Handle Pages  . . . . . . . . . . . .   63
            Function 15. Get/Set Page Map  . . . . . . . . . . . . . .   65
              Get Page Map subfunction . . . . . . . . . . . . . . . .   65
              Set Page Map subfunction . . . . . . . . . . . . . . . .   67
              Get & Set Page Map subfunction . . . . . . . . . . . . .   69
              Get Size of Page Map Save Array subfunction  . . . . . .   71


                                                                        iii





            Function 16. Get/Set Partial Page Map  . . . . . . . . . .   73
              Get Partial Page Map subfunction . . . . . . . . . . . .   73
              Set Partial Page Map subfunction . . . . . . . . . . . .   76
              Get Size of Partial Page Map Save Array subfunction  . .   78
            Function 17. Map/Unmap Multiple Handle Pages . . . . . . .   80
              Mapping Multiple Pages . . . . . . . . . . . . . . . . .   80
              Unmapping Multiple Pages . . . . . . . . . . . . . . . .   80
              Mapping and Unmapping Multiple Pages Simultaneously  . .   80
              Alternate Mapping and Unmapping Methods  . . . . . . . .   81
              Logical Page/Physical Page Method  . .OF THE EXPANDED MEMORY MANAGER
            Which method should your program use?  . . . . . . . . . .  199
            The "open handle" technique  . . . . . . . . . . . . . . .  199
            The "get interrupt vector" technique . . . . . . . . . . .  204

          Appendix C
          EXPANDED MEMORY MANAGER IMPLEMENTATION GUIDELINES
            The amount of expanded memory supported  . . . . . . . . .  206
            The number of handles supported  . . . . . . . . . . . . .  206
            Handle Numbering . . . . . . . . . . . . . . . . . . . . .  206
            New handle type:  Handles versus Raw Handles . . . . . . .  206
            The system Raw Handle (Raw Handle = 0000h) . . . . . . . .  207
            Terminate and Stay Resident (TSR) Program Cooperation  . .  208
            Accelerator Cards  . . . . . . . . . . . . . . . . . . . .  208

          Appendix D
          OPERATING SYSTEM/ENVIRONMENT USE OF FUNCTION 28
            Examples . . . . . . . . . . . . . . . . . . . . . . . . .  209
              Example 1  . . . . . . . . . . . . . . . . . . . . . . .  209
              Example 2  . . . . . . . . . . . . . . . . . . . . . . .  210
              Example 3  . . . . . . . . . . . . . . . . . . . . . . .  211

          GLOSSARY

          INDEX















                                                                          v





          Chapter 1
          INTRODUCTION


               Because even the maximum amount (640K bytes) of conventional
               memory isn't always enough for large application programs,
               Lotus Development Corporation, Intel Corporation, and Micro-
               soft Corporation created the Lotus/Intel/Microsoft (LIM)
               Expanded Memory Specification.

               The LIM Expanded Memory Specification defines the software
               interface between the Expanded Memory Manager (EMM) -- a
               device driver that controls and manages expanded memory --
               and application programs that use expanded memory.


          What is Expanded Memory?

               Expanded memory is memory beyond DOS's 640K-byte limit.  The
               LIM specification supports up to 32M bytes of expanded
               memory.  Because the 8086, 8088, and 80286 (in real mode)
               microprocessors can physically address only 1M bytes of
               memory, they access expanded memory through a window in
               their physical address range.  The next section explains how
               this is done.


          How Expanded Memory Works

               Expanded memory is divided into segments called logical
               pages.  These pages are typically 16K bytes of memory.  Your
               computer accesses logical pages through a physical block of
               memory called a page frame.  The page frame contains
               multiple physical pages, pages that the microprocessor can
               address directly.  Physical pages are also typically 16K
               bytes of memory.

               This page frame serves as a window into expanded memory.
               Just as your computer screen is a window into a large
               spreadsheet, so the page frame is a window into expanded
               memory.

               A logical page of expanded memory can be mapped into (made
               to appear in) any one of the physical pages in the page
               frame.  Thus, a read or write to the physical page actually
               becomes a read or write to the associated logical page.  One
               logical page can be mapped into the page frame for each
               physical page.

               Figure 1-1 shows the relationship among the page frame,
               physical pages, and logical pages.


          Introduction                                                    1





                                                       32M +--------------+
                                                          /|              |
                                                           |              |
                                                     /     |              |
                                                           |              |
                                                /          |              |
                                                           |              |
                                           /               |              |
                                                           |   Expanded   |
                                      /                    |    Memory    |
          1024K +--------------+                           |              |
                | / / / / / /  | /                         |              |
           960K +--------------+                           |              |
                |  Page Frame  |                           |              |
                |              |                           |              |
                | 12 16K-Byte  |                           |              |
                |   Physical   |                           |              |
                |    Pages     |                           |              |
           768K +--------------+                           | Divided into |
                | / / / / / /  | \                         |   logical    |
           640K +--------------+                           |    pages     |
                |              |   \                       |              |
                |              |                           |              |
                |              |     \                     |              |
                |              |                           |              |
                | 24 16K-Byte  |       \                   |              |
                |   Physical   |                           |              |
                |    Pages*    |         \                 |              |
                |              |                           |              |
                |              |           \               |              |
                |              |                           |              |
                |              |             \             |              |
           256K +--------------+                           |              |
                |              |               \           |              |
                | / / / / / /  |                           |              |
                |              |                 \         |              |
                | / / / / / /  |                           |              |
                |              |                   \       |              |
                | / / / / / /  |                           |              |
                |              |                     \     |              |
              0 +--------------+                           |              |
                                                       \   |              |
                                                           |              |
          *Intended for operating                        \ |              |
           system/environment use only                   0 +--------------+



          Figure 1-1.  Expanded Memory




          Introduction                                                    2





               The page frame is located above 640K bytes.  Normally, only
               video adapters, network cards, and similar devices exist
               between 640K and 1024K.

               This specification also defines methods for operating
               systems and environments to access expanded memory through
               physical pages below 640K bytes.  These methods are intended
               for operating system/environment developers only.













































          Introduction                                                    3





          Chapter 2
          WRITING PROGRAMS THAT USE EXPANDED MEMORY


               This chapter describes what every program must do to use
               expanded memory and describes more advanced techniques of
               using expanded memory.

               This chapter also lists programming guidelines you should
               follow when writing programs that use expanded memory and
               provides the listings of some example programs.


          What Every Program Must Do

               This section describes the steps every program must take to
               use expanded memory.

               In order to use expanded memory, applications must perform
               these steps in the following order:

               1.  Determine if EMM is installed.

               2.  Determine if enough expanded memory pages exist for your
                   application.  (Function 3)

               3.  Allocate expanded memory pages.  (Function 4, 18, or 27)

               4.  Get the page frame base address.  (Function 2)

               5.  Map in expanded memory pages.  (Function 5 or 17)

               6.  Read/write/execute data in expanded memory, just as if
                   it were conventional memory.

               7.  Return expanded memory pages to expand memory pool
                   before exiting.  (Function 6 or 18)

               Table 2-1 overviews the functions while Chapter 3 describes
               each of these functions in detail.  Example programs at the
               end of this chapter illustrate using expanded memory.












          Writing Programs That Use Expanded Memory                       4





          Table 2-1.  The Basic Functions
          ----------------------------------------------------------------

          Function                        Description

          ----------------------------------------------------------------

             1         The Get Status Function returns a status code
                       indicating whether the memory manager hardware is
                       working correctly.

             2         The Get Page Frame Address function returns the
                       address where the 64K-byte page frame is located.

             3         The Get Unallocated Page Count function returns the
                       number of unallocated pages (pages available to your
                       program) and the total number of pages in expanded
                       memory.

             4         The Allocate Pages function allocates the number of
                       pages requested and assigns a unique EMM handle to
                       these pages.

             5         The Map/Unmap Handle Page function maps a logical
                       page to a specific physical page anywhere in the
                       mappable regions of system memory.

             6         The Deallocate Pages deallocates the logical pages
                       currently allocated to an EMM handle.

             7         The Get Version function returns the version number
                       of the memory manager software.

          ----------------------------------------------------------------



          Advanced Programming

               In addition to the basic functions, the Lotus/Intel/Micro-
               soft Expanded Memory Specification provides several advanced
               functions which enhance the capabilities of software that
               uses expanded memory.

               The following sections describe the advanced programming
               capabilities and list the advanced EMM functions.


          Note............................................................
               Before using the advanced functions, programs should first
               call Function 7 (Get Version) to determine whether the
               installed version of EMM supports these functions.

          Writing Programs That Use Expanded Memory                       5





          Saving The State of Mapping Hardware

               Some software (such as interrupt service routines, device
               drivers, and resident software) must save the current state
               of the mapping hardware, switch mapping contexts, manipulate
               sections of expanded memory, and restore the original
               context of the memory mapping hardware.  Use Functions 8 and
               9 or 15 and 16 to save the state of the hardware.


          Retrieving Handle and Page Counts

               Some utility programs need to keep track of how expanded
               memory is being used; use Functions 12 through 14 to do
               this.


          Mapping and Unmapping Multiple Pages

               Mapping multiple pages reduces the overhead an application
               must perform during mapping.  Function 17 lets a program map
               (or unmap) multiple pages at one time.

               In addition, you can map pages using segment addresses
               instead of physical pages.  For example, if the page frame
               base address is set to D000, you can map to either physical
               page 0 or segment D000.  Function 25 (Get Mappable Physical
               Address Array) returns a cross reference between all
               expanded memory physical pages and their corresponding
               segment values.


          Reallocating Pages

               Reallocating pages (Function 18) lets applications dynami-
               cally allocate expanded memory pages without acquiring
               another handle or obtain a handle without allocating pages.
               Reallocating pages is an efficient means for applications to
               obtain and release expanded memory pages.


          Using Handles and Assigning Names to Handles

               This specification lets you associate a name with a handle,
               so a family of applications can share information in
               expanded memory.  For example, a software package consisting
               of a word processor, spreadsheet, and print spooler can
               share the same data among the different applications.  The
               print spooler could use a handle name to reference data that
               either the spreadsheet or word processor put in expanded
               memory and could check for data in a particular handle
               name's expanded memory pages.

          Writing Programs That Use Expanded Memory                       6





               Use Function 20 (Set Handle Name subfunction) to assign a
               handle name to an EMM handle or Function 21 (Search for
               Named Handle subfunction) to obtain the EMM handle as-
               sociated with the handle name.  In addition, you can use
               Function 14 (Get Handle Pages) to determine the number of
               expanded memory pages allocated to an EMM handle.


          Using Handle Attributes

               In addition to naming a handle, you can use Function 19 to
               associate an attribute (volatile or non-volatile) with a
               handle name.  A non-volatile attribute enables expanded
               memory pages to preserve their data through a warmboot.
               With a volatile attribute, the data is not preserved.  The
               default attribute for handles is volatile.

               Because using this function depends on the capabilities of
               the expanded memory hardware installed in the system, you
               should use the Get Attribute Capability subfunction before
               attempting to assign an attribute to a handle's pages.


          Altering Page Maps and Jumping/Calling

               You can use Functions 22 (Alter Page Map & Jump) and 23
               (Alter Page Map & Call) to map a new set of values into the
               map registers and transfer program control to a specified
               address within expanded memory.  These functions can be used
               to load and execute code in expanded memory.  An application
               using this feature can significantly reduce the amount of
               conventional memory it requires.  Programs can load needed
               modules into expanded memory at run time and use Functions
               22 and 23 to transfer control to these modules.

               Using expanded memory to store code can improve program
               execution in many ways.  For example, sometimes programs
               need to be divided into small overlays because of conven-
               tional memory size limitations.  Overlays targeted for
               expanded memory can be very large because LIM EMS 4.0
               supports up to 32M bytes of expanded memory.  This method of
               loading overlays improves overall system performance by
               conserving conventional memory and eliminating conventional
               memory allocation errors.


          Moving or Exchanging Memory Regions

               Using Function 24 (Move/Exchange Memory Region), you can
               easily move and exchange data between conventional and
               expanded memory.  Function 24 can manipulate up to one
               megabyte of data with one function call.  Although applica-

          Writing Programs That Use Expanded Memory                       7





               tions can perform this operation without this function,
               having the expanded memory manager do it reduces the amount
               of overhead for the application.

               In addition, this function checks for overlapping regions
               and performs all the necessary mapping, preserving the
               mapping context from before the exchange/move call.


          Getting the Amount of Mappable Memory

               Function 25 enables applications to determine the total
               amount of mappable memory the hardware/system currently
               supports.  Not all expanded memory boards supply the same
               number of physical pages (map registers).

               The Get Mappable Physical Address Array Entries subfunction
               returns the total number of physical pages the expanded
               memory hardware/system is capable of supporting.  The Get
               Mappable Physical Array subfunction returns a cross refer-
               ence between physical page numbers and the actual segment
               address for each of the physical pages.


          Operating System Functions

               In addition to the functions for application programs, this
               specification defines functions for operating systems/en-
               vironments.  These functions can be disabled at any time by
               the operating system/environment, so programs should not
               depend on their presence.  Applications that avoid this
               warning and use these functions run a great risk of being
               incompatible with other programs, including the operating
               system.



















          Writing Programs That Use Expanded Memory                       8





          Table 2-2.  The Advanced Functions
          ----------------------------------------------------------------

          Function                        Description

          ----------------------------------------------------------------

             8         The Save Page Map saves the contents of the page
                       mapping registers from all expanded memory boards in
                       an internal save area.

             9         The Restore Page Map function restores (from an
                       internal save area) the page mapping register
                       contents on the expanded memory boards for a
                       particular EMM handle.

             10        Reserved.

             11        Reserved.

             12        The Get Handle Count function returns the number of
                       open EMM handles in the system.

             13        The Get Handle Pages function returns the number of
                       pages allocated to a specific EMM handle.

             14        The Get All Handle Pages function returns an array
                       of the active EMM handles and the number of pages
                       allocated to each one.

             15        The Get/Set Page Map subfunction saves or restores
                       the mapping context for all mappable memory regions
                       (conventional and expanded) in a destination array
                       which the application supplies.

             16        The Get/Set Partial Page Map subfunction provides a
                       mechanism for saving a partial mapping context for
                       specific mappable memory regions in a system.

             17        The Map/Unmap Multiple Handle Pages function can, in
                       a single invocation, map (or unmap) logical pages
                       into as many physical pages as the system supports.

             18        The Reallocate Pages function can increase or
                       decrease the amount of expanded memory allocated to
                       a handle.

             19        The Get/Set Handle Attribute function allows an
                       application program to determine and set the
                       attribute associated with a handle.



          Writing Programs That Use Expanded Memory                       9





          Table 2-2.  The Advanced Functions (continued)
          ----------------------------------------------------------------

          Function                        Description

          ----------------------------------------------------------------

             20        The Get/Set Handle Name function gets the eight
                       character name currently assigned to a handle and
                       can assign an eight character name to a handle.

             21        The Get Handle Directory function returns informa-
                       tion about active handles and the names assigned to
                       each.

             22        The Alter Page Map & Jump function alters the memory
                       mapping context and transfers control to the
                       specified address.

             23        The Alter Page Map & Call function alters the speci-
                       fied mapping context and transfers control to the
                       specified address.  A return can then restore the
                       context and return control to the caller.

             24        The Move/Exchange Memory Region function copies or
                       exchanges a region of memory from conventional to
                       conventional memory, conventional to expanded
                       memory, expanded to conventional memory, or expanded
                       to expanded memory.

             25        The Get Mappable Physical Address Array function
                       returns an array containing the segment address and
                       physical page number for each mappable physical page
                       in a system.

             26        The Get Expanded Memory Hardware Information
                       function returns an array containing the hardware
                       capabilities of the expanded memory system.

             27        The Allocate Standard/Raw Pages function allocates
                       the number of standard or non-standard size pages
                       that the operating system requests and assigns a
                       unique EMM handle to these pages.

             28        The Alternate Map Register Set function enables an
                       application to simulate alternate sets of hardware
                       mapping registers.

             29        The Prepare Expanded Memory Hardware for Warm Boot
                       function prepares the expanded memory hardware for
                       an "impending" warm boot.


          Writing Programs That Use Expanded Memory                      10





          Table 2-2.  The Advanced Functions (continued)
          ----------------------------------------------------------------

          Function                        Description

          ----------------------------------------------------------------

             30        The Enable/Disable OS/E function enables operating
                       systems developers to enable and disable functions
                       designed for operating system use.

          ----------------------------------------------------------------









































          Writing Programs That Use Expanded Memory                      11





          Programming Guidelines

               The following section contains guidelines for programmers
               writing applications that use EMM.

               o   Do not put a program's stack in expanded memory.

               o   Do not replace interrupt 67h.  This is the interrupt
                   vector the EMM uses.  Replacing interrupt 67h could
                   result in disabling the Expanded Memory Manager.

               o   Do not map into conventional memory address space your
                   application doesn't own.  Applications that use the EMM
                   to swap into conventional memory space, must first
                   allocate this space from the operating system.  If the
                   operating system is not aware that a region of memory it
                   manages is in use, it will think it is available.  This
                   could have disastrous results.  EMM should not be used
                   to "allocate" conventional memory.  DOS is the proper
                   manager of conventional memory space.  EMM should only
                   be used to swap data in conventional memory space
                   previously allocated from DOS.

               o   Applications that plan on using data aliasing in
                   expanded memory must check for the presence of expanded
                   memory hardware.  Data aliasing occurs when mapping one
                   logical page into two or more mappable segments.  This
                   makes one 16K-byte expanded memory page appear to be in
                   more than one 16K-byte memory address space.  Data
                   aliasing is legal and sometimes useful for applications.

                   Software-only expanded memory emulators cannot perform
                   data aliasing.  A simple way to distinguish software
                   emulators from actual expanded memory hardware is to
                   attempt data aliasing and check the results.  For
                   example, map one logical page into four physical pages.
                   Write to physical page 0.  Read physical pages 1-3 to
                   see if the data is there as well.  If the data appears
                   in all four physical pages, then expanded memory
                   hardware is installed in the system, and data aliasing
                   is supported.

               o   Applications should always return expanded memory pages
                   to the expanded memory manager upon termination.  These
                   pages will be made available for other applications.  If
                   unneeded pages are not returned to the expanded memory
                   manager, the system could "run out" of expanded memory
                   pages or expanded memory handles.

               o   Terminate and stay resident programs (TSR's) should
                   ALWAYS save the state of the map registers before
                   changing them.  Since TSR's may interrupt other programs

          Writing Programs That Use Expanded Memory                      12





                   which may be using expanded memory, they must not change
                   the state of the page mapping registers without first
                   saving them.  Before exiting, TSR's must restore the
                   state of the map registers.

                   The following sections describe the three ways to save
                   and restore the state of the map registers.

                   1.  Save Page Map and Restore Page Map (Functions 8 and
                       9).  This is the simplest of the three methods.  The
                       EMM saves the map register contents in its own data
                       structures -- the application does not need to
                       provide extra storage locations for the mapping
                       context.  The last mapping context to be saved,
                       under a particular handle, will be restored when a
                       call to Restore Page Map is issued with the same
                       handle.  This method is limited to one mapping
                       context for each handle and saves the context for
                       only LIM standard 64K-byte page frames.

                   2.  Get/Set Page Map (Function 15).  This method
                       requires the application to allocate space for the
                       storage array.  The EMM saves the mapping context in
                       an array whose address is passed to the EMM.  When
                       restoring the mapping context with this method, an
                       application passes the address of an array which
                       contains a previously stored mapping context.

                       This method is preferable if an application needs to
                       do more than one save before a restore.  It provides
                       a mechanism for switching between more than one
                       mapping context.

                   3.  Get/Set Partial Page Map (Function 16).  This method
                       provides a way for saving a partial mapping context.
                       It should be used when the application does not need
                       to save the context of all mappable memory.  This
                       function also requires that the storage array be
                       part of the application's data.

               o   All functions using pointers to data structures must
                   have those data structures in memory which will not be
                   mapped out.  Functions 22 and 23 (Alter Map & Call and
                   Alter Map & Jump) are the only exceptions.









          Writing Programs That Use Expanded Memory                      13





          Examples

               This section lists four example programs that demonstrate
               the use of expanded memory.


          Example 1

               This program was written using the Microsoft C compiler
               Version 3.0.  EMM function calls are made with the int86
               function found in the dos.h library.  To create an ex-
               ecutable program use the following compile command line:

                         msc /Gs /Oat /Ml program,,program;

          #include <dos.h>
          #include <stdio.h>

          #define EMM_INT                 0x67  /* EMM interrupt number */
          #define GET_PAGE_FRAME          0x41  /* EMM get page frame */
                                                /* function number */
          #define GET_UNALLOC_PAGE_COUNT  0x42  /* EMM get unallocated */
                                                /* page count */
                                                /* function number */
          #define ALLOCATE_PAGES          0x43  /* EMM allocate pages */
                                                /* function number */
          #define MAP_PAGES               0x44  /* EMM map pages */
                                                /* function number */
          #define DEALLOCATE_PAGES        0x45  /* EMM deallocate pages */
                                                /* function number */
          #define DEVICE_NAME_LENGTH      8     /* length of a device */
                                                /* name string */
          #define TRUE                    1
          #define FALSE                   0

          union REGS input_regs, output_regs;
          struct SREGS segment_regs;
          int pf_addr;

          /*------------------------------------------------------------*/
          /* Routine to convert a segment:offset pair to a far ptr.     */
          /*------------------------------------------------------------*/
          char *build_ptr (segment, offset)

              unsigned int segment;
              unsigned int offset;
          {
              char *ptr;

              ptr = (char *)(((unsigned long)segment << 16) + offset);
              return (ptr);
          }

          Writing Programs That Use Expanded Memory                      14





          /*------------------------------------------------------------*/
          /* Function which determines whether EMM device driver        */
          /* is installed.                                              */
          /*------------------------------------------------------------*/
          char emm_installed()

          {
              char *EMM_device_name = "EMMXXXX0";
              char *int_67_device_name_ptr;

              /*--------------------------------------------------------*/
              /* AH = DOS get interrupt vector function.                */
              /*--------------------------------------------------------*/
              input_regs.h.ah = 0x35;

              /*--------------------------------------------------------*/
              /* AL = EMM interrupt vector number.                      */
              /*--------------------------------------------------------*/
              input_regs.h.al = EMM_INT;
              intdosx (&input_regs, &output_regs, &segment_regs);

              /*--------------------------------------------------------*/
              /* Upon return ES:0Ah points to location where            */
              /* device name should be.                                 */
              /*--------------------------------------------------------*/
              int_67_device_name_ptr = build_ptr (segment_regs.es, 0x0A);

              /*--------------------------------------------------------*/
              /* Compare memory with EMM device name.                   */
              /*--------------------------------------------------------*/
              if (memcmp (EMM_device_name, int_67_device_name_ptr,
                                             DEVICE_NAME_LENGTH) == 0)
                  return (TRUE);
              else
                  return (FALSE);
          }

          /*------------------------------------------------------------*/
          /* Function which determines if there are enough unallocated  */
          /* expanded memory pages for the application.                 */
          /*------------------------------------------------------------*/
          char enough_unallocated_pages (pages_needed)

              int pages_needed;
          {
              input_regs.h.ah = GET_UNALLOCATED_PAGE_COUNT;
              int86 (EMM_INT, &input_regs, &output_regs);
              if (output_regs.h.ah != 0 || pages_needed > output_regs.x.bx)
                  return (FALSE);
              else
                  return (TRUE);
          }

          Writing Programs That Use Expanded Memory                      15





          /*------------------------------------------------------------*/
          /* Function which allocates expanded memory pages and passes  */
          /* back to the main EMM handle.                               */
          /*------------------------------------------------------------*/
          char allocate_expanded_memory_pages (pages_needed,emm_handle_ptr)

              int pages_needed;
              unsigned int *emm_handle_ptr;
          {
              input_regs.h.ah = ALLOCATE_PAGES;
              input_regs.x.bx = pages_needed;
              int86 (EMM_INT, &input_regs, &output_regs);
              if (output_regs.h.ah == 0) {
                  *emm_handle_ptr = output_regs.x.dx;
                  return (TRUE);
              }
              else
                  return (FALSE);
          }

          /*------------------------------------------------------------*/
          /* Routine to map a logical page to a physical page.          */
          /*------------------------------------------------------------*/
          char map_expanded_memory_pages (emm_handle, physical_page,
                                                             logical_page)
              unsigned int emm_handle;
              int physical_page;
              int logical_page;
          {
              input_regs.h.ah = MAP_PAGES;
              input_regs.h.al = physical_page;
              input_regs.x.bx = logical_page;
              input_regs.x.dx = emm_handle;
              int86 (EMM_INT, &input_regs, &output_regs);
              if (output_regs.h.ah == 0)
                  return (TRUE);
              else
                  return (FALSE);
          }














          Writing Programs That Use Expanded Memory                      16





          /*------------------------------------------------------------*/
          /* Routine which gets the page frame base address from EMM.   */
          /*------------------------------------------------------------*/
          char get_page_frame_address (pf_ptr)

              char **pf_ptr;
          {
              input_regs.h.ah = GET_PAGE_FRAME;
              int86 (EMM_INT, &input_regs, &output_regs);
              if (output_regs.h.ah != 0)       /* check EMM status */
                  return (FALSE);
              else
                 *pf_ptr = build_ptr (output_regs.x.bx, 0);
              return (TRUE);
          }

          /*------------------------------------------------------------*/
          /* Routine to release all expanded memory pages allocated     */
          /* by an EMM handle.                                          */
          /*------------------------------------------------------------*/

          char deallocate_expanded_memory_pages (emm_handle)

              unsigned int emm_handle;
          {
              input_regs.h.ah = DEALLOCATE_PAGES;
              input_regs.x.dx = emm_handle;
              int86 (EMM_INT, &input_regs, &output_regs);
              if (output_regs.h.ah == 0)
                  return (TRUE);
              else
                  return (FALSE);
          }

          main()

          {
              unsigned int emm_handle;
              char *pf_addr;
              int pages_needed;
              int physical_page;
              int logical_page;
              int index;

              /*--------------------------------------------------------*/
              /* Determine if EMM is installed.                         */
              /*--------------------------------------------------------*/
              if (!emm_installed())
                  exit(1);




          Writing Programs That Use Expanded Memory                      17





              /*--------------------------------------------------------*/
              /* Determine if enough expanded memory pages exist for    */
              /* application.                                           */
              /*--------------------------------------------------------*/
              pages_needed = 1;
              if (!enough_unallocated_pages (pages_needed))
                  exit(1);

              /*--------------------------------------------------------*/
              /* Allocate expanded memory pages.                        */
              /*--------------------------------------------------------*/
              if (!allocate_expanded_memory_pages (pages_needed,
                                                             &emm_handle))
                  exit(1);

              /*--------------------------------------------------------*/
              /* Map in the required pages.                             */
              /*--------------------------------------------------------*/
              physical_page = 0;
              logical_page = 0;
              if (!map_expanded_memory_pages (emm_handle, physical_page,
                                                            logical_page))
                  exit(1);

              /*--------------------------------------------------------*/
              /* Get expanded memory page frame address.                */
              /*--------------------------------------------------------*/
              if (!get_page_frame_address (&pf_addr))
                  exit(1);

              /*--------------------------------------------------------*/
              /* Write to expanded memory.                              */
              /*--------------------------------------------------------*/
              for (index = 0; index < 0x3fff; index++)
                  pf_addr[index] = index;

              /*--------------------------------------------------------*/
              /* Return expanded memory pages before exiting.           */
              /*--------------------------------------------------------*/
              if (!deallocate_expanded_memory_pages (emm_handle))
                  exit(1);
          }











          Writing Programs That Use Expanded Memory                      18





          Example 2

          This program shows you how to use the basic functions of the LIM
          Expanded Memory Specification with Turbo Pascal.  The program
          does the following:

               1.  Makes sure the LIM Expanded Memory Manager (EMM) has
                   been installed.

               2.  Displays the version number of the EMM.

               3.  Determines if there are enough pages of memory for the
                   program.  It then displays the total number of EMM pages
                   present in the system and the number available for use.

               4.  Requests the desired number of pages from the EMM.

               5.  Maps a logical page into one of the physical pages.

               6.  Displays the base address of our EMM memory page frame.
                   Performs a simple read/write test on the EMM memory.

               7.  Returns the EMM memory given to us back to the EMM.

               8.  Exits.

          All the calls are structured to return the result or error code
          of the Expanded Memory function performed as an integer.  If the
          error code is not zero, an error has occurred, a simple error
          procedure is called, and the program terminates.

          Type
            ST3  = string[3];
            ST80 = string[80];
            ST5  = string[5];

            Registers = record
              case integer of
                1: (AX,BX,CX,DX,BP,SI,DI,DS,ES,FLAGS: Integer);
                2: (AL,AH,BL,BH,CL,CH,DL,DH         : Byte);
              end;

          Const
            EMM_INT                    = $67;
            DOS_Int                    = $21;
            GET_PAGE_FRAME             = $41;
            GET_UNALLOCATED_PAGE_COUNT = $42;
            ALLOCATE_PAGES             = $43;
            MAP_PAGES                  = $44;
            DEALLOCATE_PAGES           = $45;
            GET_VERSION                = $46;
            STATUS_OK                  = 0;

          Writing Programs That Use Expanded Memory                      19





            {------------------------------------------------------------}
            { Assume the application needs one EMM page.                 }
            {------------------------------------------------------------}
            APPLICATION_PAGE_COUNT = 1;

          Var
            Regs: Registers;

            Emm_handle,
            Page_Frame_Base_Address,
            Pages_Needed,
            Physical_Page,
            Logical_Page,
            Offset,
            Error_Code,
            Pages_EMM_Available,
            Total_EMM_Pages,
            Available_EMM_Pages: Integer;

            Version_Number,
            Pages_Number_String: ST3;

            Verify: Boolean;

            {------------------------------------------------------------}
            { The function Hex_String converts an integer into a four    }
            { character hexadecimal number (string) with leading zeros.  }
            {------------------------------------------------------------}
            Function Hex_String (Number: Integer): ST5;
              Function Hex_Char (Number: Integer): Char;
                Begin
                  If Number < 10 then
                    Hex_Char := Char (Number + 48)
                  else
                    Hex_Char := Char (Number + 55);
                end; { Function Hex_char }

            Var
              S: ST5;

            Begin
              S := '';
              S := Hex_Char ((Number shr 1) div 2048);
              Number := (((Number shr 1) mod 2048) shl 1) + (Number and 1);
              S := S + Hex_Char (Number div 256);
              Number := Number mod 256;
              S := S + Hex_Char (Number div 16);
              Number := Number mod 16;
              S := S + Hex_Char (Number);
              Hex_String := S + 'h';
            end; { Function Hex_String }


          Writing Programs That Use Expanded Memory                      20





            {------------------------------------------------------------}
            { The function Emm_Installed checks to see if the            }
            { EMM is loaded in memory.  It does this by looking          }
            { for the string 'EMMXXXX0', which should be located         }
            { at 10 bytes from the beginning of the code segment the     }
            { EMM interrupt, 67h, points to.                             }
            {------------------------------------------------------------}
            Function Emm_Installed: Boolean;
              Var
                Emm_Device_Name   : string[8];
                Int_67_Device_Name: string[8];
                Position          : integer;
                Regs              : registers;

              Begin
                Int_67_Device_Name := '';
                Emm_Device_Name    := 'EMMXXXX0';
                with Regs do
                  Begin
                    {----------------------------------------------------}
                    { Get the code segment interrupt 67h points to       }
                    { the EMM interrupt by using DOS function 35h.       }
                    { (get interrupt vector)                             }
                    {----------------------------------------------------}
                    AH := $35;
                    AL := EMM_INT;
                    Intr (DOS_Int, Regs);
                    {----------------------------------------------------}
                    { The ES pseudo-register contains the segment        }
                    { address pointed to by interrupt 67h.  Create an    }
                    { eight character string from the eight successive   }
                    { bytes at address ES:$000A (10 bytes from ES)       }
                    {----------------------------------------------------}
                    For Position := 0 to 7 do
                      Int_67_Device_Name :=
                        Int_67_Device_Name + Chr (mem[ES:Position + $0A]);
                    Emm_Installed := True;
                    {----------------------------------------------------}
                    { If the string is the EMM manager signature,        }
                    { 'EMMXXXX0', then EMM is installed and ready for    }
                    { use.  If not, then EMM is not present.             }
                    {----------------------------------------------------}
                    If Int_67_Device_Name <> Emm_Device_Name
                      then Emm_Installed := False;
                  end; { with Regs do }
              end; { Function Emm_Installed }







          Writing Programs That Use Expanded Memory                      21





            {------------------------------------------------------------}
            { This function returns the total number of EMM pages        }
            { present in the system, and the number of EMM pages that    }
            { are available.                                             }
            {------------------------------------------------------------}
            Function EMM_Pages_Available
              (Var Total_EMM_Pages, Pages_Available: Integer): Integer;
              Var
                Regs: Registers;

              Begin
                with Regs do
                  Begin
                    {----------------------------------------------------}
                    { Get the number of currently unallocated pages and  }
                    { the total number of pages in the system from EMM.  }
                    { Load pseudo-registers prior to invoking EMM.       }
                    {    AH = get unallocated page count function        }
                    {----------------------------------------------------}
                    AH := GET_UNALLOCATED_PAGE_COUNT;
                    Intr (EMM_INT, Regs);
                    {----------------------------------------------------}
                    { Unload the pseudo-registers after invoking EMM.    }
                    {    BX = currently unallocated pages                }
                    {    DX = total pages in the system                  }
                    {    AH = status                                     }
                    {----------------------------------------------------}
                    Pages_Available := BX;
                    Total_EMM_Pages := DX;
                    EMM_Pages_Available := AH;
                  end;
              end; { Function EMM_Pages_Available }


            {------------------------------------------------------------}
            { This function requests the specified number of pages       }
            { from the EMM.                                              }
            {------------------------------------------------------------}
            Function Allocate_Expanded_Memory_Pages
              (Pages_Needed: Integer; Var Handle: Integer): Integer;
              Var
                Regs: Registers;











          Writing Programs That Use Expanded Memory                      22





              Begin
                with Regs do
                  Begin
                    {----------------------------------------------------}
                    { Allocate the specified number of pages from EMM.   }
                    { Load pseudo-registers prior to invoking EMM.       }
                    {    AH = allocate pages function.                   }
                    {    BX = number of pages to allocate.               }
                    {----------------------------------------------------}
                    AH := ALLOCATE_PAGES;
                    BX := Pages_Needed;
                    Intr (EMM_INT, Regs);
                    {----------------------------------------------------}
                    { Unload the pseudo-registers after invoking EMM.    }
                    {    DX = EMM handle                                 }
                    {    AH = status                                     }
                    {----------------------------------------------------}
                    Handle := DX;
                    Allocate_Expanded_Memory_Pages := AH;
                  end;
              end; { Function Allocate_Expanded_Memory_Pages }


            {------------------------------------------------------------}
            { This function maps a logical page allocated by the         }
            { Allocate_Expanded_Memory_Pages function into one of the    }
            { four physical pages.                                       }
            {------------------------------------------------------------}
            Function Map_Expanded_Memory_Pages
              (Handle, Logical_Page, Physical_Page: Integer): Integer;
              Var
                Regs: Registers;

              Begin
                with Regs do
                  Begin
                    {----------------------------------------------------}
                    { Map a logical page at a physical page.             }
                    { Load pseudo-registers prior to invoking EMM.       }
                    {    AH = map page function                          }
                    {    DX = handle                                     }
                    {    BX = logical page number                        }
                    {    AL = physical page number                       }
                    {----------------------------------------------------}
                    AH := MAP_PAGES;
                    DX := Handle;
                    BX := Logical_Page;
                    AL := Physical_Page;
                    Intr (EMM_INT, Regs);




          Writing Programs That Use Expanded Memory                      23





                    {----------------------------------------------------}
                    { Unload the pseudo-registers after invoking EMM.    }
                    {    AH = status                                     }
                    {----------------------------------------------------}
                    Map_Expanded_Memory_Pages := AH;
                  end; { with Regs do }
              end; { Function Map_Expanded_Memory_Pages }


            {------------------------------------------------------------}
            { This function gets the physical address of the EMM page    }
            { frame we are using.  The address returned is the segment   }
            { of the page frame.                                         }
            {------------------------------------------------------------}
            Function Get_Page_Frame_Base_Address
              (Var Page_Frame_Address: Integer): Integer;
              Var
                Regs: Registers;

              Begin
                with Regs do
                  Begin
                    {----------------------------------------------------}
                    { Get the page frame segment address from EMM.       }
                    { Load pseudo-registers prior to invoking EMM.       }
                    {    AH = get page frame segment function            }
                    {----------------------------------------------------}
                    AH := GET_PAGE_FRAME;
                    Intr (EMM_INT, Regs);
                    {----------------------------------------------------}
                    { Unload the pseudo-registers after invoking EMM.    }
                    {    BX = page frame segment address                 }
                    {    AH = status                                     }
                    {----------------------------------------------------}
                    Page_Frame_Address := BX;
                    Get_Page_Frame_Base_Address := AH;
                  end; { with Regs do }
              end; { Function Get_Page_Frame_Base_Address }


            {------------------------------------------------------------}
            { This function releases the EMM memory pages allocated to   }
            { us, back to the EMM memory pool.                           }
            {------------------------------------------------------------}
            Function Deallocate_Expanded_Memory_Pages
              (Handle: Integer): Integer;
              Var
                Regs: Registers;





          Writing Programs That Use Expanded Memory                      24





              Begin
                with Regs do
                  Begin
                    {----------------------------------------------------}
                    { Deallocate the pages allocated to an EMM handle.   }
                    { Load pseudo-registers prior to invoking EMM.       }
                    {    AH = deallocate pages function                  }
                    {    DX = EMM handle                                 }
                    {----------------------------------------------------}
                    AH := DEALLOCATE_PAGES;
                    DX := Handle;
                    Intr (EMM_INT, Regs);
                    {----------------------------------------------------}
                    { Unload the pseudo-registers after invoking EMM.    }
                    {    AH = status                                     }
                    {----------------------------------------------------}
                    Deallocate_Expanded_Memory_Pages := AH;
                  end; { with Regs do }
              end; { Function Deallocate_Expanded_Memory_Pages }


            {------------------------------------------------------------}
            { This function returns the version number of the EMM as     }
            { a three-character string.                                  }
            {------------------------------------------------------------}
            Function Get_Version_Number (Var Version_String: ST3): Integer;
              Var
                Regs: Registers;
                Integer_Part, Fractional_Part: Char;

              Begin
                with Regs do
                  Begin
                    {----------------------------------------------------}
                    { Get the version of EMM.                            }
                    { Load pseudo-registers prior to invoking EMM.       }
                    {    AH = get EMM version function                   }
                    {----------------------------------------------------}
                    AH := GET_VERSION;
                    Intr (EMM_INT, Regs);













          Writing Programs That Use Expanded Memory                      25





                    {----------------------------------------------------}
                    { If the version number returned was OK, then        }
                    { convert it to a three-character string.            }
                    {----------------------------------------------------}
                    If AH=STATUS_OK then
                      Begin
                        {------------------------------------------------}
                        { The upper four bits of AH are the integer      }
                        { portion of the version number, the lower four  }
                        { bits are the fractional portion.  Convert the  }
                        { integer value to ASCII by adding 48.           }
                        {------------------------------------------------}
                        Integer_Part    := Char (AL shr 4  + 48);
                        Fractional_Part := Char (AL and $F + 48);
                        Version_String  := Integer_Part + '.' +
                                                          Fractional_Part;
                      end; { If AH=STATUS_OK }
                    {----------------------------------------------------}
                    { Unload the pseudo-registers after invoking EMM.    }
                    {    AH = status                                     }
                    {----------------------------------------------------}
                    Get_Version_Number := AH;
                  end; { with Regs do }
              end; { Function Get_Version_Number }


            {------------------------------------------------------------}
            { This procedure prints an error message passed by the       }
            { caller, prints the error code passed by the caller in hex, }
            { and then terminates the program with an error level of 1.  }
            {------------------------------------------------------------}
            Procedure Error (Error_Message: ST80; Error_Number: Integer);
              Begin
                Writeln (Error_Message);
                Writeln ('  Error_Number = ', Hex_String (Error_Number));
                Writeln ('EMM test program aborting.');
                Halt (1);
              end; { Procedure Error }


          {--------------------------------------------------------------}
          { This program is an example of the basic EMM functions that   }
          { you need in order to use EMM memory with Turbo Pascal.       }
          {--------------------------------------------------------------}
          Begin
            ClrScr;
            Window (5,2,77,22);






          Writing Programs That Use Expanded Memory                      26





            {------------------------------------------------------------}
            { Determine if the Expanded Memory Manager is installed.  If }
            { not, then terminate 'main' with an ErrorLevel code of 1.   }
            {------------------------------------------------------------}
            If not (Emm_Installed) then
              Begin
                Writeln ('The LIM EMM is not installed.');
                Halt (1);
              end
            else
              Begin
                { Get the version number and display it }
                Error_Code := Get_Version_Number (Version_Number);
                If Error_Code <> STATUS_OK then
                  Error ('Error getting EMM version number.', Error_Code)
                else
                  Writeln ('LIM Expanded Memory Manager, version ',
                           Version_Number, ' is ready for use.');
              end;
            Writeln;

            {------------------------------------------------------------}
            { Determine if there are enough expanded memory pages for    }
            { this application.                                          }
            {------------------------------------------------------------}
            Pages_Needed := APPLICATION_PAGE_COUNT;
            Error_Code   := EMM_Pages_Available (Total_EMM_Pages,
                                                 Available_EMM_Pages);
            If Error_Code <> STATUS_OK then
              Error ('Error determining number of EMM pages available.',
                     Error_Code);
            Writeln ('There are a total of ', Total_EMM_Pages,
                     ' expanded memory pages present in this system.');
            Writeln ('  ', Available_EMM_Pages,
                     ' of those pages are available for use.');
            Writeln;

            {------------------------------------------------------------}
            { If there is an insufficient number of pages for the        }
            { application, then report the error and terminate the EMM   }
            { example program.                                           }
            {------------------------------------------------------------}
            If Pages_Needed > Available_EMM_Pages then
              Begin
                Str (Pages_Needed, Pages_Number_String);
                Error ('We need ' + Pages_Number_String +
                       ' EMM pages.  There are not that many available.',
                       Error_Code);
              end; { Pages_Needed > Available_EMM_Pages }




          Writing Programs That Use Expanded Memory                      27





            {------------------------------------------------------------}
            { Allocate expanded memory pages for our use.                }
            {------------------------------------------------------------}
            Error_Code :=
              Allocate_Expanded_Memory_Pages (Pages_Needed, Emm_Handle);
            Str (Pages_Needed, Pages_Number_String);
            If Error_Code <> STATUS_OK then
              Error ('EMM test program failed trying to allocate '
                     + Pages_Number_String
                     + ' pages for usage.', Error_Code);
            Writeln (APPLICATION_PAGE_COUNT,
                     ' EMM page(s) allocated for the EMM test program.');
            Writeln;

            {------------------------------------------------------------}
            { Map in the required logical pages to the physical pages    }
            { given to us, in this case just one page.                   }
            {------------------------------------------------------------}
            Logical_Page  := 0;
            Physical_Page := 0;
            Error_Code := Map_Expanded_Memory_Pages (Emm_Handle,
                                                     Logical_Page,
                                                     Physical_Page);
            If Error_Code <> STATUS_OK then
              Error ('EMM test program failed trying to map '
                     + 'logical pages into physical pages.',
                     Error_Code);

            Writeln ('Logical Page ',
                     Logical_Page,
                     ' successfully mapped into Physical Page ',
                     Physical_Page);
            Writeln;

            {------------------------------------------------------------}
            { Get the expanded memory page frame address.                }
            {------------------------------------------------------------}
            Error_Code := Get_Page_Frame_Base_Address
                            (Page_Frame_Base_Address);
            If Error_Code <> STATUS_OK then
              Error ('EMM test program unable to get the base Page'
                     + ' Frame Address.',
                     Error_Code);
            Writeln ('The base address of the EMM page frame is = '
                     + Hex_String (Page_Frame_Base_Address));
            Writeln;







          Writing Programs That Use Expanded Memory                      28





            {------------------------------------------------------------}
            { Write a test pattern to expanded memory.                   }
            {------------------------------------------------------------}
            For Offset := 0 to 16382 do
              Begin
                Mem[Page_Frame_Base_Address:Offset] := Offset mod 256;
              end;

            {------------------------------------------------------------}
            { Make sure that what is in EMM memory is what was just      }
            { written.                                                   }
            {------------------------------------------------------------}
            Writeln ('Testing EMM memory.');

            Offset := 1;
            Verify := True;
            while (Offset <= 16382) and (Verify = True) do
              Begin
                If Mem[Page_Frame_Base_Address:Offset] <> Offset mod 256
                  then Verify := False;
                Offset := Succ (Offset);
              end; { while (Offset <= 16382) and (Verify = True) }

            {------------------------------------------------------------}
            { If what is read does not match what was written,           }
            { an error occurred.                                         }
            {------------------------------------------------------------}
            If not Verify then
              Error ('What was written to EMM memory was not found during'
                     + ' memory verification test.',
                     0);
            Writeln ('EMM memory test successful.');
            Writeln;

            {------------------------------------------------------------}
            { Return the expanded memory pages given to us back to the   }
            { EMM memory pool before terminating our test program.       }
            {------------------------------------------------------------}
            Error_Code := Deallocate_Expanded_Memory_Pages (Emm_Handle);
            If Error_Code <> STATUS_OK then
              Error ('EMM test program was unable to deallocate '
                     + 'the EMM pages in use.',
                     Error_Code);
            Writeln (APPLICATION_PAGE_COUNT,
                     ' pages(s) deallocated.');
            Writeln;
            Writeln ('EMM test program completed.');

          end.




          Writing Programs That Use Expanded Memory                      29





          Example 3

               This program is written in Microsoft's macro assembler.


          CODE SEGMENT
               ASSUME CS:CODE, DS:CODE

          MOV   AX,CS
          MOV   DX,AX
               .
               .
               .
          check_emm_installed:

          MOV   AH,35h                  ; AH = DOS get interrupt vector
                                        ; function
          MOV   AL,67h                  ; AL = EMM interrupt vector number
          INT   21h
          MOV   DI,0Ah                  ; ES:DI points to where device
                                        ; name should be
          LEA   SI,EMM_device_name      ; DS:SI points to ASCII string
                                        ; containing EMM device name

          MOV   CX,device_name_length   ; set up loop counter for string op
          CLD                           ; set up direction flag for forward
          REPE  CMPSB                   ; Compare the strings
          JNE   exit                    ; IF strings not equal THEN exit
                                        ; ELSE
          check_enough_unallocated_pages:

          MOV   AH,41h                  ;    AH = EMM get unallocated page
                                        ;    count function code
          INT   67h
          OR    AH,AH                   ; Check EMM status
          JNZ   emm_error_handler       ; IF error THEN goto error handler
                                        ; ELSE
          allocate_expanded_memory_pages:

          MOV   AH,43h                  ;    AH = EMM allocate pages
                                        ;    function code
          MOV   BX,2                    ;    BX = number of pages needed
          INT   67h
          OR    AH,AH                   ; Check EMM status
          JNZ   emm_error_handler       ; IF error THEN goto error handler
                                        ; ELSE
          MOV   emm_handle,DX           ;    save EMM handle

          map_expanded_memory_pages:

          MOV   AH,44h                  ; AH = EMM map pages function
          MOV   DX,emm_handle           ; DX = application's handle

          Writing Programs That Use Expanded Memory                      30





          map_0_to_0:

          MOV   BX,0                    ; BX = logical page 0
          MOV   AL,0                    ; AL = physical page 0
          INT   67h
          OR    AH,AH                   ; Check EMM status
          JNZ   emm_error_handler       ; If error THEN goto error handler
                                        ; ELSE
          get_page_frame_address:

          MOV   AH,41h                  ; AH = EMM get page frame base
                                        ; address function
          INT   67h
          OR    AH,AH                   ; Check EMM status
          JNZ   emm_error_handler       ; IF error THEN goto error handler
          MOV   pf_addr,BX              ; ELSE save pf_addr

          write_to_expanded_memory:     ; Write zeros to memory mapped at
                                        ; physical page 0
          MOV   AX,pf_addr
          MOV   ES,AX                   ; ES points to physical page 0
          MOV   DI,0                    ; DI indexes into physical page 0
          MOV   AL,0                    ; Initialize AL for string STOSB
          MOV   CX,4000h                ; Initialize loop counter to length
                                        ; of expanded memory page size
          CLD                           ; set up direction flag for forward
          REP   STOSB

          deallocate_pages:

          MOV   AH,45h                  ; AH = EMM deallocate pages
                                        ; function
          MOV   DX,emm_handle
          INT   67h                     ; return handle's pages to EMM
          OR    AH,AH                   ; Check EMM status
          JNZ   emm_error_handler       ; IF error THEN goto error handler

          exit:

          MOV   AH,4Ch                  ; AH = DOS exit function
          INT   21h                     ; return to DOS


          EMM_device_name DB 'EMMXXXX0' ; ASCII EMM device name string

          device_name_length EQU 8

          CODE ENDS
               END




          Writing Programs That Use Expanded Memory                      31





          Example 4

               This program is an example of how to exchange a 256K-byte
               block of data from conventional memory to expanded memory.


          CODE SEGMENT
               ASSUME CS:CODE, DS:CODE
               .
               .
               .
          xchg_packet_set_up:

          ;DS:SI = xchg_packet

          MOV   AX,SEG xchg_packet
          MOV   DS,AX
          MOV   SI,OFFSET xchg_packet

          ;Moving 256K of data from conventional memory to expanded memory

          MOV   WORD PTR [SI].region_length[0],0
          MOV   WORD PTR [SI].region_length[2],4
          MOV   [SI].src_mem_type,0
          MOV   [SI].dest_mem_type,1

          ;starting at segment: 4000h, offset: 0

          MOV   [SI].src_init_seg_page,4000h
          MOV   [SI].src_init_offset,0

          ;Move data into expanded memory logical page 0, offset 0.

          MOV   [SI].dest_init_seg_page,0
          MOV   [SI].dest_init_offset,0

          ;Initialize for future compatibility

          MOV   [SI].src_handle,0

          ;Need handle for expanded memory destination.

          MOV   DX,emm_handle
          MOV   [SI].dest_handle,DX

          ;AX = EMM Exchange Memory function

          MOV   AX,5701h
          INT   67h
          OR    AH,AH
          JNZ   emm_error_handler


          Writing Programs That Use Expanded Memory                      32





          xchg_struct                    STRUC
             region_length               DD ?
             src_mem_type                DB ?
             src_handle                  DW ?
             src_init_offset             DW ?
             src_init_seg_page           DW ?
             dest_mem_type               DB ?
             dest_handle                 DW ?
             dest_init_offset            DW ?
             dest_init_seg_page          DW ?
          xchg_struct                    ENDS

          xchg_packet                    xchg_struct

          CODE  ENDS
                END





































          Writing Programs That Use Expanded Memory                      33





          Chapter 3
          EMM FUNCTIONS


               This chapter provides you with a standardized set of
               expanded memory functions.  Because they are standardized,
               you avoid potential compatibility problems with other
               expanded memory programs that also adhere to the memory
               manager specification.  Programs that deal directly with the
               hardware or that don't adhere to this specification will be
               incompatible.

               Table 3-1 presents a sequential list of the EMM functions.
               The remainder of this chapter provides detailed descriptions
               of each function.


          Table 3-1.  List of EMM Functions
          ----------------------------------------------------------------

          Number             Function Name                Hex Value   Page

          ----------------------------------------------------------------

             1    Get Status                                40h         37

             2    Get Page Frame Address                    41h         38

             3    Get Unallocated Page Count                42h         40

             4    Allocate Pages                            43h         42

             5    Map/Unmap Handle Page                     44h         46

             6    Deallocate Pages                          45h         49

             7    Get Version                               46h         51

             8    Save Page Map                             47h         53

             9    Restore Page Map                          48h         55

            10    Reserved                                  49h         57

            11    Reserved                                  4Ah         58

            12    Get Handle Count                          4Bh         59

            13    Get Handle Pages                          4Ch         61

            14    Get All Handle Pages                      4Dh         63


          EMM Functions                                                  34





          Table 3-1.  List of EMM Functions (continued)
          ----------------------------------------------------------------

          Number             Function Name                Hex Value   Page

          ----------------------------------------------------------------

            15    Get Page Map                              4E00h       65
                  Set Page Map                              4E01h       67
                  Get & Set Page Map                        4E02h       69
                  Get Size of Page Map Save Array           4E03h       71

            16    Get Partial Page Map                      4F00h       73
                  Set Partial Page Map                      4F01h       76
                  Get Size of Partial Page Map
                     Save Array                             4F02h       78

            17    Map/Unmap Multiple Handle Pages
                  (Physical page number mode)               5000h       82
                  Map/Unmap Multiple Handle Pages
                  (Segment address mode)                    5001h       85

            18    Reallocate Pages                          51h         88

            19    Get Handle Attribute                      5200h       92
                  Set Handle Attribute                      5201h       94
                  Get Handle Attribute Capability           5202h       96

            20    Get Handle Name                           5300h       98
                  Set Handle Name                           5301h      100

            21    Get Handle Directory                      5400h      102
                  Search for Named Handle                   5401h      105
                  Get Total Handles                         5402h      107

            22    Alter Page Map & Jump
                  (Physical page number mode)               5500h      109
                  Alter Page Map & Jump
                  (Segment address mode)                    5501h      109

            23    Alter Page Map & Call
                  (Physical page number mode)               5600h      113
                  Alter Page Map & Call
                  (Segment address mode)                    5601h      113
                  Get Page Map Stack Space Size             5602h      118

            24    Move Memory Region                        5700h      120
                  Exchange Memory Region                    5701h      126

            25    Get Mappable Physical Address Array       5800h      132
                  Get Mappable Physical Address Array
                     Entries                                5801h      136

          EMM Functions                                                  35





          Table 3-1.  List of EMM Functions (continued)
          ----------------------------------------------------------------

          Number             Function Name                Hex Value   Page

          ----------------------------------------------------------------

            26    Get Hardware Configuration Array          5900h      138
                  Get Unallocated Raw Page Count            5901h      142

            27    Allocate Standard Pages                   5A00h      144
                  Allocate Raw Pages                        5A01h      147

            28    Get Alternate Map Register Set            5B00h      153
                  Set Alternate Map Register Set            5B01h      157
                  Get Alternate Map Save Array Size         5B02h      161
                  Allocate Alternate Map Register Set       5B03h      163
                  Deallocate Alternate Map Register Set     5B04h      166
                  Allocate DMA Register Set                 5B05h      168
                  Enable DMA on Alternate Map
                     Register Set                           5B06h      170
                  Disable DMA on Alternate Map
                     Register Set                           5B07h      173
                  Deallocate DMA Register Set               5B08h      175

            29    Prepare Expanded Memory Hardware
                     for Warmboot                           5Ch        177

            30    Enable OS/E Function Set                  5D00h      179
                  Disable OS/E Function Set                 5D01h      182
                  Return OS/E Access Key                    5D02h      185

          ----------------------------------------------------------------




















          EMM Functions                                                  36





          Function 1. Get Status



          PURPOSE

               The Get Status function returns a status code indicating
               whether the memory manager is present and the hardware is
               working correctly.


          CALLING PARAMETERS

               AH = 40h
                   Contains the Get Status Function.


          REGISTERS MODIFIED

               AX


          STATUS

               AH = 0   SUCCESSFUL.
                   The manager is present in the system, and the hardware
                   is working correctly.

               AH = 80h   NON-RECOVERABLE.
                   The manager detected a malfunction in the memory manager
                   software.

               AH = 81h   NON-RECOVERABLE.
                   The manager detected a malfunction in the expanded
                   memory hardware.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the memory manager is not
                   defined.


          EXAMPLE

          MOV   AH,40h                   ; load function code
          INT   67h                      ; call the memory manager
          OR    AH,AH                    ; check EMM status
          JNZ   emm_err_handler          ; jump to error handler on error






          EMM Functions                                                  37





          Function 2. Get Page Frame Address



          PURPOSE

               The Get Page Frame Address function returns the segment
               address where the page frame is located.


          CALLING PARAMETERS

               AH = 41h
                   Contains the Get Page Frame Address function.


          RESULTS

               These results are valid only if the status returned is zero.

               BX = page frame segment address
                   Contains the segment address of the page frame.


          REGISTERS MODIFIED

               AX, BX


          STATUS

               AH = 0   SUCCESSFUL.
                   The manager has returned the page frame address in the
                   BX register.

               AH = 80h   NON-RECOVERABLE.
                   The manager detected a malfunction in the memory manager
                   software.

               AH = 81h   NON-RECOVERABLE.
                   The manager detected a malfunction in the expanded
                   memory hardware.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the memory manager is not
                   defined.







          EMM Functions                                                  38





          Function 2. Get Page Frame Address



          EXAMPLE

          page_frame_segment             DW ?

          MOV   AH,41h                   ; load function code
          INT   67h                      ; call the memory manager
          OR    AH,AH                    ; check EMM status
          JNZ   emm_err_handler          ; jump to error handler on error
          MOV   page_frame_segment,BX    ; save page frame address








































          EMM Functions                                                  39





          Function 3. Get Unallocated Page Count



          PURPOSE

               The Get Unallocated Page Count function returns the number
               of unallocated pages and the total number of expanded memory
               pages.


          CALLING PARAMETERS

               AH = 42h
                   Contains the Get Unallocated Page Count function.


          RESULTS

               These results are valid only if the status returned is zero.

               BX = unallocated pages
                   The number of expanded memory pages that are currently
                   available for use (unallocated).

               DX = total pages
                   The total number of expanded memory pages.


          REGISTERS MODIFIED

               AX, BX, DX


          STATUS

               AH = 0   SUCCESSFUL.
                   The manager has returned the number of unallocated pages
                   and the number of total pages in expanded memory.

               AH = 80h   NON-RECOVERABLE.
                   The manager detected a malfunction in the memory manager
                   software.

               AH = 81h   NON-RECOVERABLE.
                   The manager detected a malfunction in the expanded
                   memory hardware.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the memory manager is not
                   defined.


          EMM Functions                                                  40





          Function 3. Get Unallocated Page Count



          EXAMPLE

          un_alloc_pages                 DW ?
          total_pages                    DW ?

          MOV   AH,42h                   ; load function code
          INT   67h                      ; call the memory manager
          OR    AH,AH                    ; check EMM status
          JNZ   emm_err_handler          ; jump to error handler on error
          MOV   un_alloc_pages,BX        ; save unallocated page count
          MOV   total_pages,DX           ; save total page count






































          EMM Functions                                                  41





          Function 4. Allocate Pages



               The Allocate Pages function allocates the number of pages
               requested and assigns a unique EMM handle to these pages.
               The EMM handle owns these pages until the application
               deallocates them.

               Handles which are assigned using this function will have
               16K-byte pages, the size of a standard expanded memory page.
               If the expanded memory board hardware isn't able to supply
               16K-byte pages, it will emulate them by combining multiple
               non-standard size pages to form a single 16K-byte page.  All
               application programs and functions that use the handles this
               function returns will deal with 16K-byte pages.

               The numeric value of the handles the EMM returns are in the
               range of 1 to 254 decimal (0001h to 00FEh).  The OS handle
               (handle value 0) is never returned by the Allocate Pages
               function.  Also, the uppermost byte of the handle will be
               zero and cannot be used by the application.  A memory
               manager should be able to supply up to 255 handles, includ-
               ing the OS handle.  An application can use Function 21 to
               find out how many handles an EMM supports.

               Allocating zero pages to a handle is not valid.  If an
               application needs to allocate 0 pages to a handle it should
               use Function 27 (Allocate Standard Pages subfunction)
               provided for this purpose.

          Note............................................................
               This note affects expanded memory manager implementors and
               operating system developers only.  Applications should not
               use the following characteristics of the memory manager.  An
               application violating this rule will be incompatible with
               future versions of Microsoft's operating systems and
               environments.

               To be compatible with this specification, an expanded memory
               manager will provide a special handle which is available to
               the operating system only.  This handle will have a value of
               0000h and will have a set of pages allocated to it when the
               expanded memory manager driver installs.  The pages that the
               memory manager will automatically allocate to handle 0000h
               are those that backfill conventional memory.  Typically,
               this backfill occurs between addresses 40000h (256K) and
               9FFFFh (640K).  However, the range can extend below and
               above this limit if the hardware and memory manager have the
               capability.



          EMM Functions                                                  42





          Function 4. Allocate Pages



               An operating system won't have to invoke Function 4 to
               obtain this handle because it can assume the handle already
               exists and is available for use immediately after the
               expanded memory device driver installs.  When an operating
               system wants to use this handle, it uses the special handle
               value of 0000h.  The operating system will be able to invoke
               any EMM function using this special handle value.  To
               allocate pages to this handle, the operating system need
               only invoke Function 18 (Reallocate Pages).

               There are two special cases for this handle:

               1.  Function 4 (Allocate Pages).  This function must never
                   return zero as a handle value.  Applications must always
                   invoke Function 4 to allocate pages and obtain a handle
                   which identifies the pages which belong to it.  Since
                   Function 4 never returns a handle value of zero, an
                   application will never gain access to this special
                   handle.

               2.  Function 6 (Deallocate Pages).  If the operating system
                   uses it to deallocate the pages which are allocated to
                   this special handle, the pages the handle owns will be
                   returned to the manager for use.  But the handle will
                   not be available for reassignment.  The manager should
                   treat a deallocate pages function request for this
                   handle the same as a reallocate pages function request,
                   where the number of pages to reallocate to this handle
                   is zero.


          CALLING PARAMETERS

               AH = 43h
                   Contains the Allocate Pages function.

               BX = num_of_pages_to_alloc
                   Contains the number of pages you want your program to
                   allocate.










          EMM Functions                                                  43





          Function 4. Allocate Pages



          RESULTS

               These results are valid only if the status returned is zero.

               DX = handle
                   Contains a unique EMM handle.  Your program must use
                   this EMM handle (as a parameter) in any function that
                   requires it.  You can use up to 255 handles.  The
                   uppermost byte of the handle will be zero and cannot be
                   used by the application.


          REGISTERS MODIFIED

               AX, DX


          STATUS

               AH = 0   SUCCESSFUL.
                   The manager has allocated the requested pages to the
                   assigned EMM handle.

               AH = 80h   NON-RECOVERABLE.
                   The manager detected a malfunction in the memory manager
                   software.

               AH = 81h   NON-RECOVERABLE.
                   The manager detected a malfunction in the expanded
                   memory hardware.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the memory manager is not
                   defined.

               AH = 85h   RECOVERABLE.
                   All EMM handles are being used.

               AH = 87h   RECOVERABLE.
                   There aren't enough expanded memory pages present in the
                   system to satisfy your program's request.

               AH = 88h   RECOVERABLE.
                   There aren't enough unallocated pages to satisfy your
                   program's request.

               AH = 89h   RECOVERABLE.
                   Your program attempted to allocate zero pages.

          EMM Functions                                                  44





          Function 4. Allocate Pages



          EXAMPLE

          num_of_pages_to_alloc          DW ?
          emm_handle                     DW ?

          MOV   BX,num_of_pages_to_alloc ; load number of pages
          MOV   AH,43h                   ; load function code
          INT   67h                      ; call the memory manager
          OR    AH,AH                    ; check EMM status
          JNZ   emm_err_handler          ; jump to error handler on error
          MOV   emm_handle,DX            ; save EMM handle






































          EMM Functions                                                  45





          Function 5. Map/Unmap Handle Pages



          PURPOSE

               The Map/Unmap Handle Page function maps a logical page at a
               specific physical page anywhere in the mappable regions of
               system memory.  The lowest valued physical page numbers are
               associated with regions of memory outside the conventional
               memory range.  Use Function 25 (Get Mappable Physical
               Address Array) to determine which physical pages within a
               system are mappable and determine the segment addresses
               which correspond to a specific physical page number.
               Function 25 provides a cross reference between physical page
               numbers and segment addresses.

               This function can also unmap physical pages, making them
               inaccessible for reading or writing.  You unmap a physical
               page by setting its associated logical page to FFFFh.

               You might unmap an entire set of mapped pages, for example,
               before loading and executing a program.  Doing so ensures
               the loaded program, if it accesses expanded memory, won't
               access the pages your program has mapped.  However, you must
               save the mapped context before you unmap the physical pages.
               This enables you to restore it later so you can access the
               memory you mapped there.  To save the mapping context, use
               Function 8, 15, or 16.  To restore the mapping context, use
               Function 9, 15, or 16.

               The handle determines what type of pages are being mapped.
               Logical pages allocated by Function 4 and Function 27
               (Allocate Standard Pages subfunction) are referred to as
               pages and are 16K bytes long.  Logical pages allocated by
               Function 27 (Allocate Raw Pages subfunction) are referred to
               as raw pages and might not be the same size as logical
               pages.


          CALLING PARAMETERS

               AH = 44h
                   Contains the Map Handle Page function.

               AL = physical_page_number
                   Contains the number of the physical page into which the
                   logical page number is to be mapped.  Physical pages are
                   numbered zero-relative.




          EMM Functions                                                  46





          Function 5. Map/Unmap Handle Pages



               BX = logical_page_number
                   Contains the number of the logical page to be mapped at
                   the physical page within the page frame.  Logical pages
                   are numbered zero-relative.  The logical page must be in
                   the range zero through (number of pages allocated to the
                   EMM handle - 1).  However, if BX contains logical page
                   number FFFFh, the physical page specified in AL will be
                   unmapped (be made inaccessible for reading or writing).

               DX = emm_handle
                   Contains the EMM handle your program received from
                   Function 4 (Allocate Pages).


          REGISTERS MODIFIED

               AX


          STATUS

               AH = 0   SUCCESSFUL.
                   The manager has mapped the page.  The page is ready to
                   be accessed.

               AH = 80h   NON-RECOVERABLE.
                   The manager detected a malfunction in the memory manager
                   software.

               AH = 81h   NON-RECOVERABLE.
                   The manager detected a malfunction in the expanded
                   memory hardware.

               AH = 83h   NON-RECOVERABLE.
                   The memory manager couldn't find the EMM handle your
                   program specified.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the memory manager isn't
                   defined.

               AH = 8Ah   RECOVERABLE.
                   The logical page is out of the range of logical pages
                   which are allocated to the EMM handle.  This status is
                   also returned if a program attempts to map a logical
                   page when no logical pages are allocated to the handle.



          EMM Functions                                                  47





          Function 5. Map/Unmap Handle Pages



               AH = 8Bh   RECOVERABLE.
                   The physical page number is out of the range of allow-
                   able physical pages.  The program can recover by
                   attempting to map into memory at a physical page which
                   is within the range of allowable physical pages.


          EXAMPLE

          emm_handle                     DW ?
          logical_page_number            DW ?
          physical_page_number           DB ?

          MOV   DX,emm_handle            ; load EMM handle
          MOV   BX,logical_page_number   ; load logical page number
          MOV   AL,physical_page_number  ; load physical page number
          MOV   AH,44h                   ; load function code
          INT   67h                      ; call the memory manager
          OR    AH,AH                    ; check EMM status
          JNZ   emm_err_handler          ; jump to error handler on error





























          EMM Functions                                                  48





          Function 6. Deallocate Pages



          PURPOSE

               Deallocate Pages deallocates the logical pages currently
               allocated to an EMM handle.  Only after the application
               deallocates these pages can other applications use them.
               When a handle is deallocated, its name is set to all ASCII
               nulls (binary zeros).

          Note............................................................
               A program must perform this function before it exits to DOS.
               If it doesn't, no other programs can use these pages or the
               EMM handle.  This means that a program using expanded memory
               should trap critical errors and control-break if there is a
               chance that the program will have allocated pages when
               either of these events occur.


          CALLING PARAMETERS

               AH = 45h
                   Contains the Deallocate Pages function.

               DX = handle
                   Contains the EMM handle returned by Function 4 (Allocate
                   Pages).


          REGISTERS MODIFIED

               AX


          STATUS

               AH = 0   SUCCESSFUL.
                   The manager has deallocated the pages previously allo-
                   cated to the EMM handle.

               AH = 80h   NON-RECOVERABLE.
                   The manager detected a malfunction in the memory manager
                   software.

               AH = 81h   NON-RECOVERABLE.
                   The manager detected a malfunction in the expanded
                   memory hardware.

               AH = 83h   NON-RECOVERABLE.
                   The manager couldn't find the specified EMM handle.

          EMM Functions                                                  49





          Function 6. Deallocate Pages



               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the memory manager is not
                   defined.

               AH = 86h   RECOVERABLE.
                   The memory manager detected a save or restore page
                   mapping context error (Function 8 or 9).  There is a
                   page mapping register state in the save area for the
                   specified EMM handle.  Save Page Map (Function 8) placed
                   it there and a subsequent Restore Page Map (Function 9)
                   has not removed it.

                   If you have saved the mapping context, you must restore
                   it before you deallocate the EMM handle's pages.


          EXAMPLE

          emm_handle                     DW ?

          MOV   DX,emm_handle            ; load EMM handle
          MOV   AH,45h                   ; load function code
          INT   67h                      ; call the memory manager
          OR    AH,AH                    ; check EMM status
          JNZ   emm_err_handler          ; jump to error handler on error
























          EMM Functions                                                  50





          Function 7. Get Version



          PURPOSE

               The Get Version function returns the version number of the
               memory manager software.


          CALLING PARAMETERS

               AH = 46h
                   Contains the Get Version function.


          RESULTS

               These results are valid only if the status returned is zero.

               AL = version number
                   Contains the memory manager's version number in binary
                   coded decimal (BCD) format.  The upper four bits contain
                   the integer digit of the version number.  The lower four
                   bits contain the fractional digit of version number.
                   For example, version 4.0 is represented like this:

                                      0100 0000
                                        /   \
                                       4  .  0

                   When checking for a version number, an application
                   should check for a version number or greater.  Vendors
                   may use the fractional digit to indicate enhancements or
                   corrections to their memory managers.  Therefore, to
                   allow for future versions of memory managers, an
                   application shouldn't depend on an exact version number.


          REGISTERS MODIFIED

               AX


          STATUS

               AH = 0   SUCCESSFUL.
                   The manager is present in the system and the hardware is
                   working correctly.




          EMM Functions                                                  51





          Function 7. Get Version



               AH = 80h   NON-RECOVERABLE.
                   The manager detected a malfunction in the memory manager
                   software.

               AH = 81h   NON-RECOVERABLE.
                   The manager detected a malfunction in the expanded
                   memory hardware.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the memory manager is not
                   defined.


          EXAMPLE

          emm_version                    DB ?

          MOV   AH,46h                   ; load function code
          INT   67h                      ; call the memory manager
          OR    AH,AH                    ; check EMM status
          JNZ   emm_err_handler          ; jump to error handler on error
          MOV   emm_version,AL           ; save version number



























          EMM Functions                                                  52





          Function 8. Save Page Map



          PURPOSE

               Save Page Map saves the contents of the page mapping
               registers on all expanded memory boards in an internal save
               area.  The function is typically used to save the memory
               mapping context of the EMM handle that was active when a
               software or hardware interrupt occurred.  (See Function 9,
               Restore Page Map, for the restore operation.)

               If you're writing a resident program, an interrupt service
               routine, or a device driver that uses expanded memory, you
               must save the state of the mapping hardware.  You must save
               this state because application software using expanded
               memory may be running when your program is invoked by a
               hardware interrupt, a software interrupt, or DOS.

               The Save Page Map function requires the EMM handle that was
               assigned to your resident program, interrupt service
               routine, or device driver at the time it was initialized.
               This is not the EMM handle that the application software was
               using when your software interrupted it.

               The Save Page Map function saves the state of the map
               registers for only the 64K-byte page frame defined in
               versions 3.x of this specification.  Since all applications
               written to LIM versions 3.x require saving the map register
               state of only this 64K-byte page frame, saving the entire
               mapping state for a large number of mappable pages would be
               inefficient use of memory.  Applications that use a mappable
               memory region outside the LIM 3.x page frame should use
               Function 15 or 16 to save and restore the state of the map
               registers.


          CALLING PARAMETERS

               AH = 47h
                   Contains the Save Page Map function.

               DX = handle
                   Contains the EMM handle assigned to the interrupt
                   service routine that's servicing the software or
                   hardware interrupt.  The interrupt service routine needs
                   to save the state of the page mapping hardware before
                   mapping any pages.




          EMM Functions                                                  53





          Function 8. Save Page Map



          REGISTERS MODIFIED

               AX


          STATUS

               AH = 0   SUCCESSFUL.
                   The manager has saved the state of the page mapping
                   hardware.

               AH = 80h   NON-RECOVERABLE.
                   The manager detected a malfunction in the memory manager
                   software.

               AH = 81h   NON-RECOVERABLE.
                   The manager detected a malfunction in the expanded
                   memory hardware.

               AH = 83h   NON-RECOVERABLE.
                   The memory manager couldn't find the EMM handle your
                   program specified.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the memory manager is not
                   defined.

               AH = 8Ch   NON-RECOVERABLE.
                   There is no room in the save area to store the state of
                   the page mapping registers.  The state of the map
                   registers has not been saved.

               AH = 8Dh   CONDITIONALLY-RECOVERABLE.
                   The save area already contains the page mapping register
                   state for the EMM handle your program specified.


          EXAMPLE

          emm_handle                     DW ?

          MOV   DX,emm_handle            ; load EMM handle
          MOV   AH,47h                   ; load function code
          INT   67h                      ; call the memory manager
          OR    AH,AH                    ; check EMM status
          JNZ   emm_err_handler          ; jump to error handler on error



          EMM Functions                                                  54





          Function 9. Restore Page Map



          PURPOSE

               The Restore Page Map function restores the page mapping
               register contents on the expanded memory boards for a
               particular EMM handle.  This function lets your program
               restore the contents of the mapping registers its EMM handle
               saved.  (See Function 8, Save Page Map for the save opera-
               tion.)

               If you're writing a resident program, an interrupt service
               routine, or a device driver that uses expanded memory, you
               must restore the mapping hardware to the state it was in
               before your program took over.  You must save this state
               because application software using expanded memory might
               have been running when your program was invoked.

               The Restore Page Map function requires the EMM handle that
               was assigned to your resident program, interrupt service
               routine, or device driver at the time it was initialized.
               This is not the EMM handle that the application software was
               using when your software interrupted it.

               The Restore Page Map function restores the state of the map
               registers for only the 64K-byte page frame defined in
               versions 3.x of this specification.  Since all applications
               written to LIM versions 3.x require restoring the map
               register state of only this 64K-byte page frame, restoring
               the entire mapping state for a large number of mappable
               pages would be inefficient use of memory.  Applications that
               use a mappable memory region outside the LIM 3.x page frame
               should use Function 15 or 16 to save and restore the state
               of the map registers.


          CALLING PARAMETERS

               AH = 48h
                   Contains the Restore Page Map function.

               DX = emm_handle
                   Contains the EMM handle assigned to the interrupt
                   service routine that's servicing the software or
                   hardware interrupt.  The interrupt service routine needs
                   to restore the state of the page mapping hardware.





          EMM Functions                                                  55





          Function 9. Restore Page Map



          REGISTERS MODIFIED

               AX


          STATUS

               AH = 0   SUCCESSFUL.
                   The manager has restored the state of the page mapping
                   registers.

               AH = 80h   NON-RECOVERABLE.
                   The manager detected a malfunction in the memory manager
                   software.

               AH = 81h   NON-RECOVERABLE.
                   The manager detected a malfunction in the expanded
                   memory hardware.

               AH = 83h   NON-RECOVERABLE.
                   The memory manager couldn't find the EMM handle your
                   program specified.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the memory manager is not
                   defined.

               AH = 8Eh   CONDITIONALLY-RECOVERABLE.
                   There is no page mapping register state in the save area
                   for the specified EMM handle.  Your program didn't save
                   the contents of the page mapping hardware, so Restore
                   Page can't restore it.


          EXAMPLE

          emm_handle                     DW ?

          MOV   DX,emm_handle            ; load EMM handle
          MOV   AH,48h                   ; load function code
          INT   67h                      ; call the memory manager
          OR    AH,AH                    ; check EMM status
          JNZ   emm_err_handler          ; jump to error handler on error






          EMM Functions                                                  56





          Function 10. Reserved



               In earlier versions of the Lotus/Intel/Microsoft Expanded
               Memory Specification, Function 10 returned the page mapping
               register I/O array.  This function is now reserved and new
               programs should not use it.

               Existing programs that use this function may still work
               correctly if the hardware is capable of supporting them.
               However, programs that use Functions 16 through 30 in
               Version 4.0 of this specification must not use Functions 10
               and 11.  These functions won't work correctly if your
               program attempts to mix the use of the new functions
               (Functions 16 through 30) and Functions 10 and 11.  Func-
               tions 10 and 11 are specific to the hardware on Intel
               expanded memory boards and will not work correctly on all
               vendors' expanded memory boards.


































          EMM Functions                                                  57





          Function 11. Reserved



               In earlier versions of the Lotus/Intel/Microsoft Expanded
               Memory Specification, Function 11 returned a page transla-
               tion array.  This function is now reserved and new programs
               should not use it.

               Existing programs that use this function may still work
               correctly if the hardware is capable of supporting them.
               However, programs that use Functions 16 through 30 in
               Version 4.0 of this specification must not use Functions 10
               and 11.  These functions won't work correctly if your
               program attempts to mix the use of the new functions
               (Functions 16 through 30) and Functions 10 and 11.  Func-
               tions 10 and 11 are specific to the hardware on Intel
               expanded memory boards and will not work correctly on all
               vendors' expanded memory boards.


































          EMM Functions                                                  58





          Function 12. Get Handle Count



          PURPOSE

               The Get Handle Count function returns the number of open EMM
               handles (including the operating system handle 0) in the
               system.


          CALLING PARAMETERS

               AH = 4Bh
                   Contains the Get Handle Count function.


          RESULTS

               These results are valid only if the status returned is zero.

               BX = total_open_emm_handles
                   Contains the number of open EMM handles [including the
                   operating system handle (0)].  This number will not
                   exceed 255.


          REGISTERS MODIFIED

               AX, BX


          STATUS

               AH = 0   SUCCESSFUL.
                   The manager has returned the number of active EMM
                   handles.

               AH = 80h   NON-RECOVERABLE.
                   The manager detected a malfunction in the memory manager
                   software.

               AH = 81h   NON-RECOVERABLE.
                   The manager detected a malfunction in the expanded
                   memory hardware.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the memory manager is not
                   defined.




          EMM Functions                                                  59





          Function 12. Get Handle Count



          EXAMPLE

          total_open_emm_handles              DW ?

          MOV   AH,4Bh                        ; load function code
          INT   67h                           ; call the memory manger
          OR    AH,AH                         ; check EMM status
          JNZ   emm_err_handler               ; jump to error handler on
                                              ; error
          MOV   total_open_emm_handles,BX     ; save total active handle
                                              ; count






































          EMM Functions                                                  60





          Function 13. Get Handle Pages



          PURPOSE

               The Get Handle Pages function returns the number of pages
               allocated to a specific EMM handle.


          CALLING PARAMETERS

               AH = 4Ch
                   Contains the Get Handle Pages function.

               DX = emm_handle
                   Contains the EMM handle.


          RESULTS

               These results are valid only if the status returned is zero.

               BX = num_pages_alloc_to_emm_handle
                   Contains the number of logical pages allocated to the
                   specified EMM handle.  This number never exceeds 2048
                   because the memory manager allows a maximum of 2048
                   pages (32M bytes) of expanded memory.


          REGISTERS MODIFIED

               AX, BX


          STATUS

               AH = 0   SUCCESSFUL.
                   The manager has returned the number of pages allocated
                   to the EMM handle.

               AH = 80h   NON-RECOVERABLE.
                   The manager detected a malfunction in the memory manager
                   software.

               AH = 81h   NON-RECOVERABLE.
                   The manager detected a malfunction in the expanded
                   memory hardware.

               AH = 83h   NON-RECOVERABLE.
                   The memory manager couldn't find the EMM handle your
                   program specified.

          EMM Functions                                                  61





          Function 13. Get Handle Pages



               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the memory manager is not
                   defined.


          EXAMPLE

          emm_handle                          DW ?
          pages_alloc_to_handle               DW ?

          MOV   DX,emm_handle                 ; load EMM handle
          MOV   AH,4Ch                        ; load function code
          INT   67h                           ; call the memory manager
          OR    AH,AH                         ; check EMM status
          JNZ   emm_err_handler               ; jump to error handler on
                                              ; error
          MOV   pages_alloc_to_handle,BX      ; save number of pages
                                              ; allocated to specified
                                              ; handle






























          EMM Functions                                                  62





          Function 14. Get All Handle Pages



          PURPOSE

               The Get All Handle Pages function returns an array of the
               open EMM handles and the number of pages allocated to each
               one.


          CALLING PARAMETERS

               AH = 4Dh
                   Contains the Get All Handle Pages function.

                   handle_page_struct              STRUC
                       emm_handle                  DW ?
                       pages_alloc_to_handle       DW ?
                   handle_page_struct              ENDS

               ES:DI = pointer to handle_page
                   Contains a pointer to an array of structures where a
                   copy of all open EMM handles and the number of pages
                   allocated to each will be stored.  Each structure has
                   these two members:

                   .emm_handle
                       The first member is a word which contains the value
                       of the open EMM handle.  The values of the handles
                       this function returns will be in the range of 0 to
                       255 decimal (0000h to 00FFh).  The uppermost byte of
                       the handle is always zero.

                   .pages_alloc_to_handle
                       The second member is a word which contains the
                       number of pages allocated to the open EMM handle.


          RESULTS

               These results are valid only if the status returned is zero.

               BX = total_open_emm_handles
                   Contains the number of open EMM handles (including the
                   operating system handle [0]).  The number cannot be zero
                   because the operating system handle is always active and
                   cannot be deallocated.  This number will not exceed 255.





          EMM Functions                                                  63





          Function 14. Get All Handle Pages



          REGISTERS MODIFIED

               AX, BX


          STATUS

               AH = 0   SUCCESSFUL.
                   The manager has returned the array.

               AH = 80h   NON-RECOVERABLE.
                   The manager detected a malfunction in the memory manager
                   software.

               AH = 81h   NON-RECOVERABLE.
                   The manager detected a malfunction in the expanded
                   memory hardware.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the memory manager is not
                   defined.


          EXAMPLE

          handle_page                    handle_page_struct 255 DUP (?)
          total_open_handles             DW ?

          MOV   AX,SEG handle_page
          MOV   ES,AX
          LEA   DI,handle_page           ; ES:DI points to handle_page
          MOV   AH,4Dh                   ; load function code
          INT   67h                      ; call the memory manager
          OR    AH,AH                    ; check the EMM status
          JNZ   emm_err_handler          ; jump to error handler on error
          MOV   total_open_handles,BX    ; save total open handle count













          EMM Functions                                                  64





          Function 15. Get/Set Page Map
          Get Page Map subfunction



          PURPOSE

               The Get Page Map subfunction saves the mapping context for
               all mappable memory regions (conventional and expanded) by
               copying the contents of the mapping registers from each
               expanded memory board to a destination array.  The applica-
               tion must pass a pointer to the destination array.  This
               subfunction doesn't require an EMM handle.

               Use this function instead of Functions 8 and 9 if you need
               to save or restore the mapping context but don't want (or
               have) to use a handle.


          CALLING PARAMETERS

               AX = 4E00h
                   Contains the Get Page Map subfunction.

               ES:DI = dest_page_map
                   Contains a pointer to the destination array address in
                   segment:offset format.  Use the Get Size of Page Map
                   Save Array subfunction to determine the size of the
                   desired array.


          RESULTS

               These results are valid only if the status returned is zero.

               dest_page_map
                   The array contains the state of all the mapping regis-
                   ters on all boards in the system.  It also contains any
                   additional information necessary to restore the boards
                   to their original state when the program invokes a Set
                   subfunction.


          REGISTERS MODIFIED

               AX


          STATUS

               AH = 0   SUCCESSFUL.
                   The manager has returned the array.

          EMM Functions                                                  65





          Function 15. Get/Set Page Map
          Get Page Map subfunction



               AH = 80h   NON-RECOVERABLE.
                   The manager detected a malfunction in the memory manager
                   software.

               AH = 81h   NON-RECOVERABLE.
                   The manager detected a malfunction in the expanded
                   memory hardware.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the memory manager is not
                   defined.

               AH = 8Fh   NON-RECOVERABLE.
                   The subfunction parameter is invalid.


          EXAMPLE

          dest_page_map                  DB ? DUP (?)

          MOV   AX,SEG dest_page_map
          MOV   ES,AX
          LEA   DI,dest_page_map         ; ES:DI points to dest_page_map
          MOV   AX,4E00h                 ; load function code
          INT   67h                      ; call the memory manager
          OR    AH,AH                    ; check EMM status
          JNZ   emm_err_handler          ; jump to error handler on error





















          EMM Functions                                                  66





          Function 15. Get/Set Page Map
          Set Page Map subfunction



          PURPOSE

               The Set Page Map subfunction restores the mapping context
               for all mappable memory regions (conventional and expanded)
               by copying the contents of a source array into the mapping
               registers on each expanded memory board in the system.  The
               application must pass a pointer to the source array.  This
               subfunction doesn't require an EMM handle.

               Use this function instead of Functions 8 and 9 if you need
               to save or restore the mapping context but don't want (or
               have) to use a handle.


          CALLING PARAMETERS

               AX = 4E01h
                   Contains the Set Page Map subfunction.

               DS:SI = source_page_map
                   Contains a pointer to the source array address in
                   segment:offset format.  The application must point to an
                   array which contains the mapping register state.  Use
                   the Get Size of Page Map Save Array subfunction to
                   determine the size of the desired array.


          REGISTERS MODIFIED

               AX


          STATUS

               AH = 0   SUCCESSFUL.
                   The manager has passed the array.

               AH = 80h   NON-RECOVERABLE.
                   The manager detected a malfunction in the memory manager
                   software.

               AH = 81h   NON-RECOVERABLE.
                   The manager detected a malfunction in the expanded
                   memory hardware.




          EMM Functions                                                  67





          Function 15. Get/Set Page Map
          Set Page Map subfunction



               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the memory manager is not
                   defined.

               AH = 8Fh   NON-RECOVERABLE.
                   The subfunction parameter is invalid.

               AH = A3h   NON-RECOVERABLE.
                   The contents of the source array have been corrupted, or
                   the pointer passed to the subfunction is invalid.


          EXAMPLE

          source_page_map                DB ? DUP (?)

          MOV   AX,SEG source_page_map
          MOV   DS,AX
          LEA   SI,source_page_map       ; DS:SI points to source_page_map
          MOV   AX,4E01h                 ; load function code
          INT   67h                      ; call the memory manager
          OR    AH,AH                    ; check EMM status
          JNZ   emm_err_handler          ; jump to error handler on error

























          EMM Functions                                                  68





          Function 15. Get/Set Page Map
          Get & Set Page Map subfunction



          PURPOSE

               The Get & Set Page Map subfunction simultaneously saves a
               current mapping context and restores a previous mapping
               context for all mappable memory regions (both conventional
               and expanded).  It first copies the contents of the mapping
               registers from each expanded memory board in the system into
               a destination array.  (The application must pass a pointer
               to the destination array.)  Then, the subfunction copies the
               contents of a source array into the mapping registers on
               each of the expanded memory boards.  (The application must
               pass a pointer to the source array.)

               Use this function instead of Functions 8 and 9 if you need
               to save or restore the mapping context but don't want (or
               have) to use a handle.


          CALLING PARAMETERS

               AX = 4E02h
                   Contains the Get & Set Page Map subfunction.

               ES:DI = dest_page_map
                   Contains a pointer to the destination array address in
                   segment:offset format.  The current contents of the map
                   registers will be saved in this array.

               DS:SI = source_page_map
                   Contains a pointer to the source array address in
                   segment:offset format.  The contents of this array will
                   be copied into the map registers.  The application must
                   point to an array which contains the mapping register
                   state.  This address is required only for the Set or Get
                   and Set subfunctions.


          RESULTS

               These results are valid only if the status returned is zero.

               dest_page_map
                   The array contains the mapping state.  It also contains
                   any additional information necessary to restore the
                   original state when the program invokes a Set subfunc-
                   tion.


          EMM Functions                                                  69





          Function 15. Get/Set Page Map
          Get & Set Page Map subfunction



          REGISTERS MODIFIED

               AX


          STATUS

               AH = 0   SUCCESSFUL.
                   The manager has returned and passed both arrays.

               AH = 80h   NON-RECOVERABLE.
                   The manager detected a malfunction in the memory manager
                   software.

               AH = 81h   NON-RECOVERABLE.
                   The manager detected a malfunction in the expanded
                   memory hardware.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the memory manager is not
                   defined.

               AH = 8Fh   NON-RECOVERABLE.
                   The subfunction parameter is invalid.

               AH = A3h   NON-RECOVERABLE.
                   The contents of the source array have been corrupted, or
                   the pointer passed to the subfunction is invalid.


          EXAMPLE

          dest_page_map                  DB ? DUP (?)

          source_page_map                DB ? DUP (?)

          MOV   AX,SEG dest_page_map
          MOV   ES,AX
          MOV   AX,SEG source_page_map
          MOV   DS,AX
          LEA   DI,dest_page_map         ; ES:DI points to dest_page_map
          LEA   SI,source_page_map       ; DS:SI points to source_page_map
          MOV   AX,4E02h                 ; load function code
          INT   67h                      ; call the memory manager
          OR    AH,AH                    ; check EMM status
          JNZ   emm_err_handler          ; jump to error handler on error


          EMM Functions                                                  70





          Function 15. Get/Set Page Map
          Get Size of Page Map Save Array subfunction



          PURPOSE

               The Get Size of Page Map Save Array subfunction returns the
               storage requirements for the array passed by the other three
               subfunctions.  This subfunction doesn't require an EMM
               handle.


          CALLING PARAMETERS

               AX = 4E03h
                   Contains the Get Size of Page Map Save Array subfunc-
                   tion.  The size of this array depends on how the
                   expanded memory system is configured and how the
                   expanded memory manager is implemented.  Therefore, the
                   size must be determined after the memory manager is
                   loaded.


          RESULTS

               These results are valid only if the status returned is zero.

               AL = size_of_array
                   Contains the number of bytes that will be transferred to
                   the memory area an application supplies whenever a
                   program requests the Get, Set, or Get and Set subfunc-
                   tions.


          REGISTERS MODIFIED

               AX


          STATUS

               AH = 0   SUCCESSFUL.
                   The manager has returned the array size.

               AH = 80h   NON-RECOVERABLE.
                   The manager detected a malfunction in the memory manager
                   software.

               AH = 81h   NON-RECOVERABLE.
                   The manager detected a malfunction in the expanded
                   memory hardware.

          EMM Functions                                                  71





          Function 15. Get/Set Page Map
          Get Size of Page Map Save Array subfunction



               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the memory manager is not
                   defined.

               AH = 8Fh   NON-RECOVERABLE.
                   The subfunction parameter is invalid.


          EXAMPLE

          size_of_array                  DB ?

          MOV   AX,4E03h                 ; load function code
          INT   67h                      ; call the memory manager
          OR    AH,AH                    ; check EMM status
          JNZ   emm_err_handler          ; jump to error handler on error
          MOV   size_of_array,AL         ; save array size































          EMM Functions                                                  72





          Function 16. Get/Set Partial Page Map
          Get Partial Page Map subfunction



          PURPOSE

               The Get Partial Page Map subfunction saves a partial mapping
               context for specific mappable memory regions in a system.
               Because this function saves only a subset of the entire
               mapping context, it uses much less memory for the save area
               and may be potentially faster than Function 15.  The
               subfunction does this by copying the contents of selected
               mapping registers from each expanded memory board to a
               destination array.

               The application must pass a pair of pointers.  The first
               points to a structure which specifies which mappable
               segments to save; the second points to the destination
               array.

               Use this function instead of Functions 8 and 9 if you need
               to save or restore the mapping context but don't want (or
               have) to use a handle.


          CALLING PARAMETERS

               AX = 4F00h
                   Contains the Get Partial Page Map subfunction.

                   partial_page_map_struct         STRUC
                       mappable_segment_count      DW ?
                       mappable_segment            DW (?) DUP (?)
                   partial_page_map_struct         ENDS

               DS:SI = partial_page_map
                   Contains a pointer to a structure which specifies only
                   those mappable memory regions which are to have their
                   mapping context saved.  The structure members are
                   described below.

                   .mappable_segment_count
                       The first member is a word which specifies the
                       number of members in the word array which immediate-
                       ly follows it.  This number should not exceed the
                       number of mappable segments in the system.






          EMM Functions                                                  73





          Function 16. Get/Set Partial Page Map
          Get Partial Page Map subfunction



                   .mappable_segment
                       The second member is a word array which contains the
                       segment addresses of the mappable memory regions
                       whose mapping contexts are to be saved.  The segment
                       address must be a mappable segment.  Use Function 25
                       to determine which segments are mappable.

               ES:DI = dest_array
                   Contains a pointer to the destination array address in
                   segment:offset format.  To determine the size of the
                   required array, see the Get Size of Partial Page Map
                   Save Array subfunction.


          RESULTS

               These results are valid only if the status returned is zero.

               dest_array
                   The array contains the partial mapping context and any
                   additional information necessary to restore this context
                   to its original state when the program invokes a Set
                   subfunction.


          REGISTERS MODIFIED

               AX


          STATUS

               AH = 0   SUCCESSFUL.
                   The manager has saved the partial map context.

               AH = 80h   NON-RECOVERABLE.
                   The manager detected a malfunction in the memory manager
                   software.

               AH = 81h   NON-RECOVERABLE.
                   The manager detected a malfunction in the expanded
                   memory hardware.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the memory manager is not
                   defined.


          EMM Functions                                                  74





          Function 16. Get/Set Partial Page Map
          Get Partial Page Map subfunction



               AH = 8Bh   NON-RECOVERABLE.
                   One of the specified segments is not a mappable segment.

               AH = 8Fh   NON-RECOVERABLE.
                   The subfunction parameter is invalid.

               AH = A3h   NON-RECOVERABLE.
                   The contents of the partial page map structure have been
                   corrupted, the pointer passed to the subfunction is
                   invalid, or the mappable_segment_count exceeds the
                   number of mappable segments in the system.


          EXAMPLE

          partial_page_map               partial_page_map_struct <>

          dest_array                     DB ? DUP (?)

          MOV   AX,SEG partial_page_map
          MOV   DS,AX
          LEA   SI,partial_page_map      ; DS:SI points to partial_page_map
          MOV   AX,SEG dest_array
          MOV   ES,AX
          LEA   DI,dest_array            ; ES:DI points to dest_array
          MOV   AX,4F00h                 ; load function code
          INT   67h                      ; call the memory manager
          OR    AH,AH                    ; check EMM status
          JNZ   emm_err_handler          ; jump to error handler on error



















          EMM Functions                                                  75





          Function 16. Get/Set Partial Page Map
          Set Partial Page Map subfunction



          PURPOSE

               The Set Partial Page Map subfunction provides a mechanism
               for restoring the mapping context for a partial mapping
               context for specific mappable memory regions in a system.
               Because this function restores only a subset of the entire
               mapping context and not the entire systems mapping context,
               it uses much less memory for the save area and is potential-
               ly faster than Function 15.  The subfunction does this by
               copying the contents of the source array to selected mapping
               registers on each expanded memory board.  The application
               passes a pointer to the source array.

               Use this function instead of Functions 8 and 9 if you need
               to save or restore the mapping context but don't want (or
               have) to use a handle.


          CALLING PARAMETERS

               AX = 4F01h
                   Contains the Set Partial Page Map subfunction

                           source_array     DB ? DUP (?)

               DS:SI = source_array
                   Contains a pointer to the source array in segment:offset
                   format.  The application must point to an array which
                   contains the partial mapping register state.  To deter-
                   mine the size of the required array, see the Get Size of
                   Partial Page Map Save Array subfunction.


          REGISTERS MODIFIED

               AX


          STATUS

               AH = 0   SUCCESSFUL.
                   The manager has restored the partial mapping context.

               AH = 80h   NON-RECOVERABLE.
                   The manager detected a malfunction in the memory manager
                   software.


          EMM Functions                                                  76





          Function 16. Get/Set Partial Page Map
          Set Partial Page Map subfunction



               AH = 81h   NON-RECOVERABLE.
                   The manager detected a malfunction in the expanded
                   memory hardware.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the memory manager is not
                   defined.

               AH = 8Fh   NON-RECOVERABLE.
                   The subfunction parameter is invalid.

               AH = A3h   NON-RECOVERABLE.
                   The contents of the source array have been corrupted, or
                   the pointer passed to the subfunction is invalid.


          EXAMPLE

          MOV   AX,SEG source_array
          MOV   DS,AX
          LEA   SI,source_array          ; DS:SI points to source_array
          MOV   AX,4F01h                 ; load function code
          INT   67h                      ; call the memory manager
          OR    AH,AH                    ; check EMM status
          JNZ   emm_err_handler          ; jump to error handler on error























          EMM Functions                                                  77





          Function 16. Get/Set Partial Page Map
          Get Size of Partial Page Map Save Array subfunction



          PURPOSE

               The Get Size of Partial Page Map Save Array subfunction
               returns the storage requirements for the array passed by the
               other two subfunctions.  This subfunction doesn't require an
               EMM handle.


          CALLING PARAMETERS

               AX = 4F02h
                   Contains the Get Size of Partial Page Map Save Array
                   subfunction.  The size of this array depends on the
                   expanded memory system configuration and the implementa-
                   tion of the expanded memory manager.  Therefore, it will
                   vary between hardware configurations and implementations
                   and must be determined after a specific memory manager
                   is loaded.

               BX = number of pages in the partial array
                   Contains the number of pages in the partial map to be
                   saved by the Get/Set Partial Page Map subfunctions.
                   This number should be the same as the mappable_seg-
                   ment_count in the Get Partial Page Map subfunction.


          RESULTS

               These results are valid only if the status returned is zero.

               AL = size_of_partial_save_array
                   Contains the number of bytes that will be transferred to
                   the memory areas supplied by an application whenever a
                   program requests the Get or Set subfunction.


          REGISTERS MODIFIED

               AX


          STATUS

               AH = 0   SUCCESSFUL.
                   The manager has returned the array size.



          EMM Functions                                                  78





          Function 16. Get/Set Partial Page Map
          Get Size of Partial Page Map Save Array subfunction



               AH = 80h   NON-RECOVERABLE.
                   The manager detected a malfunction in the memory manager
                   software.

               AH = 81h   NON-RECOVERABLE.
                   The manager detected a malfunction in the expanded
                   memory hardware.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the memory manager is not
                   defined.

               AH = 8Bh   NON-RECOVERABLE.
                   The number of pages in the partial array is outside the
                   range of physical pages in the system.

               AH = 8Fh   NON-RECOVERABLE.
                   The subfunction parameter is invalid.


          EXAMPLE

          number_of_pages_to_map              DW ?
          size_of_partial_save_array          DB ?

          MOV   BX,number_of_pages_to_map
          MOV   AX,4F02h                      ; load function code
          INT   67h                           ; call the memory manager
          OR    AH,AH                         ; check EMM status
          JNZ   emm_err_handler               ; jump to error handler on
                                              ; error
          MOV   size_of_partial_save_array,AL ; save array size
















          EMM Functions                                                  79





          Function 17. Map/Unmap Multiple Handle Pages



          PURPOSE

               This function can, in a single invocation, map (or unmap)
               logical pages into as many physical pages as the system
               supports.  Consequently, it has less execution overhead than
               mapping pages one at a time.  For applications which do a
               lot of page mapping, this is the preferred mapping method.


          Mapping Multiple Pages

               The handle passed to this function determines what type of
               logical pages are being mapped.  Logical pages that Function
               4 and Function 27 (Allocate Standard Pages subfunction)
               allocate are referred to as pages and are 16K bytes.
               Logical pages that Function 27 (Allocate Raw Pages subfunc-
               tion) allocates are referred to as raw pages and might not
               be the same size as the pages Function 4 and Function 27
               (Allocate Standard Pages subfunction) allocate.


          Unmapping Multiple Pages

               This function can make specific physical pages unavailable
               for reading or writing.  A logical page which is unmapped
               from a specific physical page cannot be read or written from
               that physical page.  The logical page which is unavailable
               (unmapped) can be made available again by mapping it, or a
               new logical page, at the physical page that was unmapped.
               Unmapping a physical page is accomplished by setting the
               logical page it is associated with to FFFFh.

               You might unmap an entire set of mapped pages, for example,
               before loading and executing a program.  This ensures that
               the loaded program won't be able to access the pages your
               program has mapped.  However, you must save the mapping
               context before you unmap the physical pages.  This enables
               you to restore it later so that you may access the memory
               you had mapped there.  You can save the mapping context with
               Functions 8, 15, or 16.  You can restore the mapping context
               with Functions 9, 15, or 16.


          Mapping and Unmapping Multiple Pages Simultaneously

               Both mapping and unmapping pages can be done in the same
               invocation.


          EMM Functions                                                  80





          Function 17. Map/Unmap Multiple Handle Pages



               Mapping or unmapping no pages is not considered an error.
               If a request to map or unmap zero pages is made, nothing is
               done and no error is returned.


          Alternate Mapping and Unmapping Methods

               You can map or unmap pages using two methods.  Both methods
               produce identical results.

               1.  The first method specifies both a logical page and a
                   physical page at which the logical page is to be mapped.
                   This method is an extension of Function 5 (Map Handle
                   Page).

               2.  The second method specifies both a logical page and a
                   corresponding segment address at which the logical page
                   is to be mapped.  While this is functionally the same as
                   the first method, it may be easier to use the actual
                   segment address of a physical page than to use a number
                   which only represents its location.  The memory manager
                   verifies whether the specified segment address falls on
                   the boundary of a mappable physical page.  The manager
                   then translates the segment address passed to it into
                   the necessary internal representation to map the pages.
























          EMM Functions                                                  81





          Function 17. Map/Unmap Multiple Handle Pages
          Logical Page/Physical Page Method


          CALLING PARAMETERS

               AX = 5000h
                   Contains the Map/Unmap Multiple Handle Pages subfunction
                   using the logical page/physical page method.

                   log_to_phys_map_struct          STRUC
                       log_page_number             DW ?
                       phys_page_number            DW ?
                   log_to_phys_map_struct          ENDS

               DX = handle
                   Contains the EMM handle.

               CX = log_to_phys_map_len
                   Contains the number of entries in the array.  For
                   example, if the array contained four pages to map or
                   unmap, then CX would contain 4.  The number in CX should
                   not exceed the number of mappable pages in the system.

               DS:SI = pointer to log_to_phys_map array
                   Contains a pointer to an array of structures that
                   contains the information necessary to map the desired
                   pages.  The array is made up of the following two
                   elements:

                   .log_page_number
                       The first member is a word which contains the number
                       of the logical page which is to be mapped.  Logical
                       pages are numbered zero-relative, so the number for
                       a logical page can only range from zero to (maximum
                       number of logical pages allocated to the handle -
                       1).

                       If the logical page number is set to FFFFh, the
                       physical page associated with it is unmapped rather
                       than mapped.  Unmapping a physical page makes it
                       inaccessible for reading or writing.

                   .phys_page_number
                       The second member is a word which contains the
                       number of the physical page at which the logical
                       page is to be mapped.  Physical pages are numbered
                       zero-relative, so the number for a physical page can
                       only range from zero to (maximum number of physical
                       pages supported in the system - 1).



          EMM Functions                                                  82





          Function 17. Map/Unmap Multiple Handle Pages
          Logical Page/Physical Page Method



          REGISTERS MODIFIED

               AX


          STATUS

               AH = 0   SUCCESSFUL.
                   The logical pages have been mapped, or unmapped, at the
                   specified physical pages.

               AH = 80h   NON-RECOVERABLE.
                   The manager has detected a malfunction in the memory
                   manager software.

               AH = 81h   NON-RECOVERABLE.
                   The manager has detected a malfunction in the expanded
                   memory hardware.

               AH = 83h   NON-RECOVERABLE.
                   The manager couldn't find the specified EMM handle.  The
                   manager doesn't currently have any information pertain-
                   ing to the specified EMM handle.  The program has
                   probably corrupted its EMM handle.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the manager is not defined.

               AH = 8Ah   RECOVERABLE.
                   One or more of the mapped logical pages is out of the
                   range of logical pages allocated to the EMM handle.  The
                   program can recover by attempting to map a logical page
                   which is within the bounds for the specified EMM handle.
                   When this error occurs, the only pages mapped were the
                   ones valid up to the point that the error occurred.

               AH = 8Bh   RECOVERABLE.
                   One or more of the physical pages is out of the range of
                   mappable physical pages, or the log_to_phys_map_len
                   exceeds the number of mappable pages in the system.  The
                   program can recover from this condition by attempting to
                   map into memory at the physical page which is in the
                   range of the physical page numbers supported by the
                   system.  When this error occurs, the only pages mapped
                   were the ones valid up to the point that the error
                   occurred.


          EMM Functions                                                  83





          Function 17. Map/Unmap Multiple Handle Pages
          Logical Page/Physical Page Method



               AH = 8Fh   NON-RECOVERABLE.
                   The subfunction parameter is invalid.


          EXAMPLE

          log_to_phys_map            log_to_phys_map_struct ? DUP (?)

          emm_handle                 DW ?

          MOV   AX,SEG log_to_phys_map
          MOV   DS,AX
          LEA   SI,log_to_phys_map            ; DS:SI points to
                                              ; log_to_phys_map
          MOV   CX,LENGTH log_to_phys_map     ; set length field
          MOV   DX,emm_handle
          MOV   AX,5000h                      ; load function code
          INT   67h                           ; call the memory manager
          OR    AH,AH                         ; check EMM status
          JNZ   emm_err_handler               ; jump to error handler on
                                              ; error



























          EMM Functions                                                  84





          Function 17. Map/Unmap Multiple Handle Pages
          Logical Page/Segment Address Method


          CALLING PARAMETERS

               AX = 5001h
                   Contains the Map/Unmap Multiple Handle Pages subfunction
                   using the logical page/segment address method.

                   log_to_seg_map_struct           STRUC
                       log_page_number             DW ?
                       mappable_segment_address    DW ?
                   log_to_seg_map_struct           ENDS

               DX = handle
                   Contains the EMM handle.

               CX = log_to_segment_map_len
                   Contains the number of entries in the array.  For
                   example, if the array contained four pages to map or
                   unmap, then CX would contain four.

               DS:SI = pointer to log_to_segment_map array
                   Contains a pointer to an array of structures that
                   contains the information necessary to map the desired
                   pages.  The array is made up of the following elements:

                   .log_page_number
                       The first member is a word which contains the number
                       of the logical pages to be mapped.  Logical pages
                       are numbered zero-relative, so the number for a
                       logical page can range from zero to (maximum number
                       of logical pages allocated to the handle - 1).

                       If the logical page number is set to FFFFh, the
                       physical page associated with it is unmapped rather
                       than mapped.  Unmapping a physical page makes it
                       inaccessible for reading or writing.

                   .mappable_segment_address
                       The second member is a word which contains the
                       segment address at which the logical page is to be
                       mapped.  This segment address must correspond
                       exactly to a mappable segment address.  The mappable
                       segment addresses are available with Function 25
                       (Get Mappable Physical Address Array).


          REGISTERS MODIFIED

               AX

          EMM Functions                                                  85





          Function 17. Map/Unmap Multiple Handle Pages
          Logical Page/Segment Address Method



          STATUS

               AH = 0   SUCCESSFUL.
                   The logical pages have been mapped (or unmapped) at the
                   specified physical pages.

               AH = 80h   NON-RECOVERABLE.
                   The manager has detected a malfunction in the memory
                   manager software.

               AH = 81h   NON-RECOVERABLE.
                   The manager has detected a malfunction in the expanded
                   memory hardware.

               AH = 83h   NON-RECOVERABLE.
                   The manager could not find the specified EMM handle.
                   The manager doesn't currently have any information
                   pertaining to the specified EMM handle.  The program has
                   probably corrupted its EMM handle.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the manager is not defined.

               AH = 8Ah   RECOVERABLE.
                   One or more of the logical pages to be mapped is out of
                   the range of logical pages allocated to the EMM handle.
                   The program can recover from this condition by mapping a
                   logical page which is within the bounds for the speci-
                   fied EMM handle.  When this error occurs, the only pages
                   mapped or unmapped were the ones valid up to the point
                   that the error occurred.

               AH = 8Bh   RECOVERABLE.
                   One or more of the mappable segment addresses specified
                   is not mappable, the segment address doesn't fall
                   exactly on a mappable address boundary, or the log_to_-
                   segment_map_len exceeds the number of mappable segments
                   in the system.  The program can recover from this
                   condition by mapping into memory on an exact mappable
                   segment address.  When this error occurs, the only pages
                   mapped were the ones valid up to the point that the
                   error occurred.

               AH = 8Fh   NON-RECOVERABLE.
                   The subfunction parameter is invalid.



          EMM Functions                                                  86





          Function 17. Map/Unmap Multiple Handle Pages
          Logical Page/Segment Address Method



          EXAMPLE

          log_to_seg_map             log_to_seg_map_struct 4 DUP (?)

          emm_handle                 DW ?

          MOV   AX,SEG log_to_seg_map
          MOV   DS,AX
          LEA   SI,log_to_seg_map             ; DS:SI points to
                                              ; log_to_seg_map
          MOV   CX,LENGTH log_to_seg_map
          MOV   DX,emm_handle
          MOV   AX,5001h                      ; load function code
          INT   67h                           ; call the memory manager
          OR    AH,AH                         ; check EMM status
          JNZ   emm_err_handler               ; jump to error handler on
                                              ; error































          EMM Functions                                                  87





          Function 18. Reallocate Pages



          PURPOSE

               This function allows an application program to increase or
               decrease (reallocate) the number of logical pages allocated
               to an EMM handle.  There are four reallocation cases of
               interest:

               1.  A reallocation count of zero.  The handle assigned to
                   the application remains assigned and is still available
                   for use by the application.  The memory manager won't
                   reassign the handle to any other application.  However,
                   the handle will have any currently allocated pages
                   returned to the memory manager.  The application must
                   invoke the Deallocate Pages function (Function 6) before
                   returning to DOS, or the handle will remain assigned and
                   no other application will be able to use it.

               2.  A reallocation count equal to the current allocation
                   count.  This is not treated as an error, and a success-
                   ful status is returned.

               3.  A reallocation count greater than the current allocation
                   count.  The memory manager will attempt to add new pages
                   to those pages already allocated to the specified EMM
                   handle.  The number of new pages added is the difference
                   between the reallocation count and the current alloca-
                   tion count.  The sequence of logical pages allocated to
                   the EMM handle remains continuous after this operation.
                   The newly allocated pages have logical page numbers
                   which begin where the previously allocated pages ended,
                   and continue in ascending sequence.

               4.  A reallocation count less than the current allocation
                   count.  The memory manager will attempt to subtract some
                   of the currently allocated pages and return them to the
                   memory manager.  The number of old pages subtracted is
                   the difference between the current allocation count and
                   the re-allocation count.  The pages are subtracted from
                   the end of the sequence of pages currently allocated to
                   the specified EMM handle.  The sequence of logical pages
                   allocated to the EMM handle remains continuous after
                   this operation.







          EMM Functions                                                  88





          Function 18. Reallocate Pages



          The handle determines what type of logical pages are being
          reallocated.  Logical pages which were originally allocated with
          Function 4 or Function 27 (Allocate Standard Pages subfunction)
          are called pages and are 16K bytes long.  Logical pages which
          were allocated with Function 27 (Allocate Raw Pages subfunction)
          are called raw pages and might not be the same size as pages
          allocated with Function 4.


          CALLING PARAMETERS

               AH = 51h
                   Contains the Reallocate Handle Pages function.

               DX = handle
                   Contains the EMM handle.

               BX = reallocation_count
                   Contains the total number of pages this handle should
                   have allocated to it after this function is invoked.


          RESULTS

               BX = number of pages allocated to handle after reallocation
                   Contains the number of pages now allocated to the EMM
                   handle after the pages have been added or subtracted.
                   If the status returned is not zero, the value in BX is
                   equal to the number of pages allocated to the handle
                   prior to the invocation of this function.  This informa-
                   tion can be used to verify that the request generated
                   the expected results.


          REGISTERS MODIFIED

               AX, BX


          STATUS

               AH = 0   SUCCESSFUL.
                   The pages specified have been added to or subtracted
                   from the handle specified.

               AH = 80h   NON-RECOVERABLE.
                   The manager has detected a malfunction in the memory
                   manager software.

          EMM Functions                                                  89





          Function 18. Reallocate Pages



               AH = 81h   NON-RECOVERABLE.
                   The manager has detected a malfunction in the expanded
                   memory hardware.

               AH = 83h   NON-RECOVERABLE.
                   The manager could not find the specified EMM handle.
                   The manager doesn't have any information pertaining to
                   the specified EMM handle.  The program may have cor-
                   rupted its EMM handle.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the manager is not defined.

               AH = 87h   RECOVERABLE.
                   The number of pages that are available in the system is
                   insufficient for the new allocation request.  The
                   program can recover from this condition by specifying
                   fewer pages be allocated to the EMM handle.

               AH = 88h   RECOVERABLE.
                   The number of unallocated pages is insufficient for the
                   new allocation request.  The program can recover from
                   this condition by either requesting again when addition-
                   al pages are available or specifying fewer pages.


          EXAMPLE

          emm_handle                          DW ?
          realloc_count                       DW ?
          current_alloc_page_count            DW ?

          MOV   DX,emm_handle                 ; specify EMM handle
          MOV   BX,realloc_count              ; specify count
          MOV   AH,51h                        ; load function code
          INT   67h                           ; call the memory manager
          OR    AH,AH                         ; check EMM status
          JNZ   emm_err_handler               ; jump to error handler on
                                              ; error
          MOV   current_alloc_page_count,BX









          EMM Functions                                                  90





          Function 19. Get/Set Handle Attribute



          Design Considerations

               This function is an option which will probably not be
               available in a typical expanded memory manager, system, or
               memory board.  Most personal computer systems disable memory
               refresh signals for a considerable period during a warm
               boot.  This can corrupt some of the data in memory boards,
               even though there is no problem with the design of the
               memory board, its operation, or the memory chips.  This
               memory refresh deficiency is present in the software design
               of the ROM BIOS in most personal computer systems.

               The majority of memory board designs, chip types, or
               personal computer systems won't be able to support the non-
               volatility feature.  The reason that this ROM BIOS deficien-
               cy is not evident in the conventional or extended memory
               area is that the ROM BIOS always initializes this area
               during a warm boot.  Memory data integrity is not a problem
               with the conventional or extended memory region, because it
               isn't physically possible to have data retained there across
               a warm boot event -- the ROM BIOS sets it to zero.

               Consequently, expanded memory board manufacturers should not
               supply this function unless their board can guarantee the
               integrity of data stored in the board's memory during a warm
               boot.  Generally, this means the memory board has an
               independent memory refresh controller which does not depend
               on the system board's memory refresh.

               If the expanded memory manager, system, or memory board
               cannot support this feature, it should return the not
               supported status described in the function.

















          EMM Functions                                                  91





          Function 19. Get/Set Handle Attribute
          Get Handle Attribute subfunction



          PURPOSE

               This subfunction returns the attribute associated with a
               handle.  The attributes are volatile or non-volatile.
               Handles with non-volatile attributes enable the memory
               manager to save the contents of a handle's pages between
               warm boots.  However, this function may be disabled with a
               user option or may not be supported by the memory board or
               system hardware.

               If the handle's attribute has been set to non-volatile, the
               handle, its name (if it is assigned one), and the contents
               of the pages allocated to the handle are all maintained
               after a warm boot.


          CALLING PARAMETERS

               AX = 5200h
                   Contains the Get Handle Attribute subfunction.

               DX = handle
                   Contains the EMM handle.


          RESULTS

               These results are valid only if the status returned is zero.

               AL = handle attribute
                   Contains the EMM handle's attribute.  The only at-
                   tributes a handle may have are volatile or non-volatile.
                   A value of zero indicates the handle is volatile.  A
                   value of one indicates that the handle is non-volatile.


          REGISTERS MODIFIED

               AX


          STATUS

               AH = 0   SUCCESSFUL.
                   The handle's attribute has been obtained.



          EMM Functions                                                  92





          Function 19. Get/Set Handle Attribute
          Get Handle Attribute subfunction



               AH = 80h   NON-RECOVERABLE.
                   The manager has detected a malfunction in the memory
                   manager software.

               AH = 81h   NON-RECOVERABLE.
                   The manager has detected a malfunction in the expanded
                   memory hardware.

               AH = 83h   NON-RECOVERABLE.
                   The manager couldn't find the specified EMM handle.  The
                   manager doesn't have any information pertaining to the
                   specified EMM handle.  The program may have corrupted
                   its EMM handle.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the manager is not defined.

               AH = 8Fh   NON-RECOVERABLE.
                   The subfunction parameter is invalid.

               AH = 91h   NON-RECOVERABLE.
                   This feature is not supported.


          EXAMPLE

          emm_handle                     DW ?
          handle_attrib                  DB ?

          MOV   DX,emm_handle            ; specify EMM handle
          MOV   AX,5200h                 ; load function code
          INT   67h                      ; call the memory manager
          OR    AH,AH                    ; check EMM status
          JNZ   emm_err_handler          ; jump to error handler on error
          MOV   handle_attrib,AL         ; save handle attribute













          EMM Functions                                                  93





          Function 19. Get/Set Handle Attribute
          Set Handle Attribute subfunction



          PURPOSE

               This subfunction can be used to modify the attribute which a
               handle has associated with it.  The attributes which a
               handle may have are volatile or non-volatile.  The non-
               volatile attribute enables the EMM to save the contents of a
               handle's pages between warm boots.  However, this function
               may be disabled with a user option or may not be supported
               by the memory board or system hardware.

               If the handle's attribute has been set to non-volatile, the
               handle, its name (if it is assigned one), and the contents
               of the pages allocated to the handle are all maintained
               after a warm boot.


          CALLING PARAMETERS

               AX = 5201h
                   Contains the Set Handle Attribute function.

               DX = handle
                   Contains the EMM handle.

               BL = new handle attribute
                   Contains the handle's new attribute.  A value of zero
                   indicates that the handle should be made volatile.  A
                   value of one indicates that the handle should be made
                   non-volatile.

                   A volatile handle attribute instructs the memory manager
                   to deallocate both the handle and the pages allocated to
                   it after a warm boot.  If all handles have the volatile
                   attribute (the default attribute) at warm boot, the
                   handle directory will be empty and all of expanded
                   memory will be initialized to zero immediately after a
                   warm boot.


          REGISTERS MODIFIED

               AX






          EMM Functions                                                  94





          Function 19. Get/Set Handle Attribute
          Set Handle Attribute subfunction



          STATUS

               AH = 0   SUCCESSFUL.
                   The handle's attribute has been modified.

               AH = 80h   NON-RECOVERABLE.
                   The manager has detected a malfunction in the memory
                   manager software.

               AH = 81h   NON-RECOVERABLE.
                   The manager has detected a malfunction in the expanded
                   memory hardware.

               AH = 83h   NON-RECOVERABLE.
                   The manager could not find the specified EMM handle.
                   The manager doesn't have any information pertaining to
                   the specified EMM handle.  The program may have cor-
                   rupted its EMM handle.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the manager is not defined.

               AH = 8Fh   NON-RECOVERABLE.
                   The subfunction parameter is invalid.

               AH = 90h   NON-RECOVERABLE.
                   The attribute type is undefined.

               AH = 91h   NON-RECOVERABLE.
                   This feature is not supported.


          EXAMPLE

          emm_handle                     DW ?
          new_handle_attrib              DB ?

          MOV   DX,emm_handle            ; specify EMM handle
          MOV   BL,new_handle_attrib     ; specify the set attribute
          MOV   AX,5201h                 ; load function code
          INT   67h                      ; call the memory manager
          OR    AH,AH                    ; check EMM status
          JNZ   emm_err_handler          ; jump to error handler on error





          EMM Functions                                                  95





          Function 19. Get/Set Handle Attribute
          Get Attribute Capability subfunction



          PURPOSE

               This subfunction can be used to determine whether the memory
               manager can support the non-volatile attribute.


          CALLING PARAMETERS

               AX = 5202h
                   Contains the Get Attribute Capability subfunction.


          RESULTS

               These results are valid only if the status returned is zero.

               AL = attribute capability
                   Contains the attribute capability.  A value of zero
                   indicates that the memory manager and hardware supports
                   only volatile handles.  A value of one indicates that
                   the memory manager/hardware supports both volatile and
                   non-volatile handles.


          REGISTERS MODIFIED

               AX


          STATUS

               AH = 0   SUCCESSFUL.
                   The attribute capability has been returned.

               AH = 80h   NON-RECOVERABLE.
                   The manager has detected a malfunction in the memory
                   manager software.

               AH = 81h   NON-RECOVERABLE.
                   The manager has detected a malfunction in the expanded
                   memory hardware.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the manager is not defined.

               AH = 8Fh   NON-RECOVERABLE.
                   The subfunction parameter is invalid.

          EMM Functions                                                  96





          Function 19. Get/Set Handle Attribute
          Get Attribute Capability subfunction



          EXAMPLE

          attrib_capability              DB ?

          MOV   AX,5202h                 ; load function code
          INT   67h                      ; call the memory manager
          OR    AH,AH                    ; check EMM status
          JNZ   emm_err_handler          ; jump to error handler on error
          MOV   attrib_capability,AL     ; save attribute capability







































          EMM Functions                                                  97





          Function 20. Get/Set Handle Name
          Get Handle Name subfunction



          PURPOSE

               This subfunction gets the eight character name currently
               assigned to a handle.  There is no restriction on the
               characters which may be used in the handle name (that is,
               anything from 00h through FFh).

               The handle name is initialized to ASCII nulls (binary zeros)
               three times:  when the memory manager is installed, when a
               handle is allocated, and when a handle is deallocated.  A
               handle with a name which is all ASCII nulls, by definition,
               has no name.  When a handle is assigned a name, at least one
               character in the name must be a non-null character in order
               to distinguish it from a handle without a name.


          CALLING PARAMETERS

               AX = 5300h
                   Contains the Get Handle Name function.

               DX = handle number
                   Contains the EMM handle.

               ES:DI = pointer to handle_name array
                   Contains a pointer to an eight-byte array into which the
                   name currently assigned to the handle will be copied.


          RESULTS

               These results are valid only if the status returned is zero.

               handle_name array
                   Contains the name associated with the specified handle.


          REGISTERS MODIFIED

               AX


          STATUS

               AH = 0   SUCCESSFUL.
                   The handle name has been returned.


          EMM Functions                                                  98





          Function 20. Get/Set Handle Name
          Get Handle Name subfunction



               AH = 80h   NON-RECOVERABLE.
                   The manager has detected a malfunction in the memory
                   manager software.

               AH = 81h   NON-RECOVERABLE.
                   The manager has detected a malfunction in the expanded
                   memory hardware.

               AH = 83h   NON-RECOVERABLE.
                   The manager couldn't find the specified EMM handle.  The
                   manager doesn't have any information on the specified
                   EMM handle.  The program may have corrupted its EMM
                   handle.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the manager is not defined.

               AH = 8Fh   NON-RECOVERABLE.
                   The subfunction parameter is invalid.


          EXAMPLE

          handle_name                    DB 8 DUP (?)
          emm_handle                     DW ?

          MOV   AX,SEG handle_name
          MOV   ES,AX
          LEA   DI,handle_name           ; ES:DI points to handle_name
          MOV   DX,emm_handle            ; specify EMM handle
          MOV   AX,5300h                 ; load function code
          INT   67h                      ; call the memory manager
          OR    AH,AH                    ; check EMM status
          JNZ   emm_err_handler          ; jump to error handler on error














          EMM Functions                                                  99





          Function 20. Get/Set Handle Name
          Set Handle Name subfunction



          PURPOSE

               This subfunction assigns an eight character name to a
               handle.  There is no restriction on the characters which may
               be used in the handle name.  The full range of values may be
               assigned to each character in a name (that is, 00h through
               FFh).

               At installation, all handles have their name initialized to
               ASCII nulls (binary zeros).  A handle with a name consisting
               of all ASCII nulls has no name.  When a handle is assigned a
               name, at least one character in the name must be a non-null
               character in order to distinguish it from a handle without a
               name.  No two handles may have the same name.

               A handle can be renamed at any time by setting the handle's
               name to a new value.  A handle can have its name removed by
               setting the handle's name to all ASCII nulls.  When a handle
               is deallocated, its name is removed (set to ASCII nulls).


          CALLING PARAMETERS

               AX = 5301h
                   Contains the Set Handle Name function.

               DX = handle number
                   Contains the EMM handle.

               DS:SI = pointer to handle_name
                   Contains a pointer to a byte array which contains the
                   name that is to be assigned to the handle.  The handle
                   name must be padded with nulls if the name is less than
                   eight characters long.


          REGISTERS MODIFIED

               AX


          STATUS

               AH = 0   SUCCESSFUL.
                   The handle name has been assigned.



          EMM Functions                                                 100





          Function 20. Get/Set Handle Name
          Set Handle Name subfunction



               AH = 80h   NON-RECOVERABLE.
                   The manager has detected a malfunction in the memory
                   manager software.

               AH = 81h   NON-RECOVERABLE.
                   The manager has detected a malfunction in the expanded
                   memory hardware.

               AH = 83h   NON-RECOVERABLE.
                   The manager couldn't find the specified EMM handle.  The
                   manager doesn't currently have any information pertain-
                   ing to the specified EMM handle.  The program may have
                   corrupted its EMM handle.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the manager is not defined.

               AH = 8Fh   NON-RECOVERABLE.
                   The subfunction parameter is invalid.

               AH = A1h   RECOVERABLE.
                   A handle with this name already exists.  The specified
                   handle was not assigned a name.


          EXAMPLE

          handle_name                    DB 'AARDVARK'
          emm_handle                     DW ?

          MOV   AX,SEG handle_name
          MOV   DS,AX
          LEA   SI,handle_name           ; DS:SI points to handle_name
          MOV   DX,emm_handle            ; specify EMM handle
          MOV   AX,5301h                 ; load function code
          INT   67h                      ; call the memory manager
          OR    AH,AH                    ; check EMM status
          JNZ   emm_err_handler          ; jump to error handler on error










          EMM Functions                                                 101





          Function 21. Get Handle Directory
          Get Handle Directory subfunction



          PURPOSE

               This function returns an array which contains all active
               handles and the names associated with each.  Handles which
               have not been assigned names have a default name of all
               ASCII nulls (binary zeros).  When a handle is first allo-
               cated, or when all the pages belonging to a handle are
               deallocated (that is, an open handle is closed), its default
               name is set to ASCII nulls.  It takes a subsequent assign-
               ment of a name for a handle to have a name after it has been
               opened.  The full range of values may be assigned to each
               character in a name (that is, 00h through FFh).

               The number of bytes required by the array is:

                           10 bytes * total number of handles

               The maximum size of this array is:

                           (10 bytes/entry) * 255 entries = 2550 bytes.


          CALLING PARAMETERS

               AX = 5400h
                   Contains the Get Handle Directory function.

                   handle_dir_struct               STRUC
                       handle_value                DW ?
                       handle_name                 DB 8 DUP (?)
                   handle_dir_struct               ENDS

               ES:DI = pointer to handle_dir
                   Contains a pointer to an area of memory into which the
                   memory manager will copy the handle directory.  The
                   handle directory is an array of structures.  There are
                   as many entries in the array as there are open EMM
                   handles.  The structure consists of the following
                   elements:

                   .handle_value
                       The first member is a word which contains the value
                       of the open EMM handle.





          EMM Functions                                                 102





          Function 21. Get Handle Directory
          Get Handle Directory subfunction



                   .handle_name
                       The second member is an 8 byte array which contains
                       the ASCII name associated with the EMM handle.  If
                       there is no name currently associated with the
                       handle, it has a value of all zeros (ASCII nulls).


          RESULTS

               These results are valid only if the status returned is zero.

               handle_dir
                   Contains the handle values and handle names associated
                   with each handle value.

               AL = number of entries in the handle_dir array
                   Contains the number of entries in the handle directory
                   array.  This is also the same as the number of open
                   handles.  For example, if only one handle is active, AL
                   will contain a one.


          REGISTERS MODIFIED

               AX


          STATUS

               AH = 0   SUCCESSFUL.
                   The handle directory has been returned.

               AH = 80h   NON-RECOVERABLE.
                   The manager has detected a malfunction in the memory
                   manager software.

               AH = 81h   NON-RECOVERABLE.
                   The manager has detected a malfunction in the expanded
                   memory hardware.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the manager is not defined.

               AH = 8Fh   NON-RECOVERABLE.
                   The subfunction parameter is invalid.



          EMM Functions                                                 103





          Function 21. Get Handle Directory
          Get Handle Directory subfunction



          EXAMPLE

          handle_dir                    handle_dir_struct 255 DUP (?)

          num_entries_in_handle_dir     DB ?

          MOV   AX,SEG handle_dir
          MOV   ES,AX
          LEA   DI,handle_dir                 ; ES:DI points to handle_dir
          MOV   AX,5400h                      ; load function code
          INT   67h                           ; call the memory manager
          OR    AH,AH                         ; check EMM status
          JNZ   emm_err_handler               ; jump to error handler on
                                              ; error
          MOV   num_entries_in_handle_dir,AL  ; save number of entries

































          EMM Functions                                                 104





          Function 21. Get Handle Directory
          Search For Named Handle subfunction



          PURPOSE

               This subfunction searches the handle name directory for a
               handle with a particular name.  If the named handle is
               found, this subfunction returns the handle number associated
               with the name.  At the time of installation, all handles
               have their names initialized to ASCII nulls.  A handle with
               a name which is all ASCII nulls has, by definition, no name.
               When a handle is assigned a name, at least one character in
               the name must be a non-null character in order to distin-
               guish it from a handle without a name.


          CALLING PARAMETERS

               AX = 5401h
                   Contains the Search for Named Handle subfunction.

               DS:SI = handle_name
                   Contains a pointer to an 8-byte string that contains the
                   name of the handle being searched for.


          RESULTS

               These results are valid only if the status returned is zero.

               DX = value of named handle
                   The value of the handle which matches the handle name
                   specified.


          REGISTERS MODIFIED

               AX, DX


          STATUS

               AH = 0   SUCCESSFUL.
                   The handle value for the named handle has been found.

               AH = 80h   NON-RECOVERABLE.
                   The manager has detected a malfunction in the memory
                   manager software.



          EMM Functions                                                 105





          Function 21. Get Handle Directory
          Search For Named Handle subfunction



               AH = 81h   NON-RECOVERABLE.
                   The manager has detected a malfunction in the expanded
                   memory hardware.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the manager is not defined.

               AH = 8Fh   NON-RECOVERABLE.
                   The subfunction parameter is invalid.

               AH = A0h   NON-RECOVERABLE.
                   No corresponding handle could be found for the handle
                   name specified.

               AH = A1h   NON-RECOVERABLE.
                   A handle found had no name (all ASCII nulls).


          EXAMPLE

          named_handle                   DB 'AARDVARK'
          named_handle_value             DW ?

          MOV   AX,SEG named_handle
          MOV   DS,AX
          LEA   SI,named_handle          ; DS:SI points to named_handle
          MOV   AX,5401h                 ; load function code
          INT   67h                      ; call the memory manager
          OR    AH,AH                    ; check EMM status
          JNZ   emm_err_handler          ; jump to error handler on error
          MOV   named_handle_value,DX    ; save value of named handle

















          EMM Functions                                                 106





          Function 21. Get Handle Directory
          Get Total Handles subfunction



          PURPOSE

               This subfunction returns the total number of handles that
               the memory manager supports, including the operating system
               handle (handle value 0).


          CALLING PARAMETERS

               AX = 5402h
                   Contains the Get Total Handles subfunction.


          RESULTS

               These results are valid only if the status returned is zero.

               BX = total_handles
                   The value returned represents the maximum number of
                   handles which a program may request the memory manager
                   to allocate memory to.  The value returned includes the
                   operating system handle (handle value 0).


          REGISTERS MODIFIED

               AX, BX


          STATUS

               AH = 0   SUCCESSFUL.
                   The total number of handles supported has been returned.

               AH = 80h   NON-RECOVERABLE.
                   The manager has detected a malfunction in the memory
                   manager software.

               AH = 81h   NON-RECOVERABLE.
                   The manager has detected a malfunction in the expanded
                   memory hardware.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the manager is not defined.

               AH = 8Fh   NON-RECOVERABLE.
                   The subfunction parameter is invalid.

          EMM Functions                                                 107





          Function 21. Get Handle Directory
          Get Total Handles subfunction



          EXAMPLE

          total_handles                  DW ?

          MOV   AX,5402h                 ; load function code
          INT   67h                      ; call the memory manager
          OR    AH,AH                    ; check EMM status
          JNZ   emm_err_handler          ; jump to error handler on error
          MOV   total_handles,BX         ; save total handle count







































          EMM Functions                                                 108





          Function 22. Alter Page Map & Jump



          PURPOSE

               This function alters the memory mapping context and trans-
               fers control to the specified address.  It is analogous to
               the FAR JUMP in the 8086 family architecture.  The memory
               mapping context which existed before the invocation of this
               function is lost.

               Mapping no pages and jumping is not considered an error.  If
               a request to map zero pages and jump is made, control is
               transferred to the target address, and this function
               performs a far jump.


          CALLING PARAMETERS

               AH = 55h
                   Contains the Alter Page Map & Jump function.

                   log_phys_map_struct             STRUC
                       log_page_number             DW ?
                       phys_page_number_seg        DW ?
                   log_phys_map_struct             ENDS

                   map_and_jump_struct             STRUC
                       target_address              DD ?
                       log_phys_map_len            DB ?
                       log_phys_map_ptr            DD ?
                   map_and_jump_struct             ENDS

               AL = physical page number/segment selector
                   Contains a code which indicates whether the value
                   contained in the

                       .log_phys_map.phys_page_number_seg

                   members are physical page numbers or are the segment
                   address representation of the physical page numbers.  A
                   zero in AL indicates that the values are physical page
                   numbers.  A one in AL indicates that the values in these
                   members are the segment address representations of the
                   physical page numbers.

               DX = handle number
                   Contains the EMM handle.




          EMM Functions                                                 109





          Function 22. Alter Page Map & Jump



               DS:SI = pointer to map_and_jump structure
                   Contains a pointer to a structure that contains the
                   information necessary to map the desired physical pages
                   and jump to the target address.  The structure consists
                   of the following elements:

                   .target_address
                       The first member is a far pointer which contains the
                       target address to which control is to be trans-
                       ferred.  The address is represented in segment:of-
                       fset format.  The offset portion of the address is
                       stored in the low portion of the double word.

                   .log_phys_map_len
                       The second member is a byte which contains the
                       number of entries in the array of structures which
                       immediately follows it.  The array is as long as the
                       application developer needs in order to map the
                       desired logical pages into physical pages.  The
                       number of entries cannot exceed the number of
                       mappable pages in the system.

                   .log_phys_map_ptr
                       The third member is a pointer to an array of struc-
                       tures which contain the logical page numbers and
                       physical pages or segment address at which they are
                       to be mapped.  Each entry in the array of structures
                       contains the following two elements:

                   .log_page_number
                       The first member of this structure is a word which
                       contains the number of the logical page to be
                       mapped.

                   .phys_page_number_seg
                       The second member of this structure is a word which
                       contains either the physical page number or the
                       segment address representation of the physical page
                       number at which the previous logical page number is
                       to be mapped.  The value passed in AL determines the
                       type of representation.


          REGISTERS MODIFIED

               AX



          EMM Functions                                                 110





          Function 22. Alter Page Map & Jump



          Note............................................................
               Values in registers which don't contain required parameters
               maintain the values across the jump.  The values in regis-
               ters (with the exception of AX) and the flag state at the
               beginning of the function are still in the registers and
               flags when the target address is reached.


          STATUS

               AH = 0   SUCCESSFUL.
                   Control has been transferred to the target address.

               AH = 80h   NON-RECOVERABLE.
                   The manager has detected a malfunction in the memory
                   manager software.

               AH = 81h   NON-RECOVERABLE.
                   The manager has detected a malfunction in the expanded
                   memory hardware.

               AH = 83h   NON-RECOVERABLE.
                   The manager could not find the specified EMM handle.
                   The manager does not currently have any information
                   pertaining to the specified EMM handle.  The program may
                   have corrupted its EMM handle.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the manager is not defined.

               AH = 8Ah   RECOVERABLE.
                   One or more of the logical pages to map into a cor-
                   responding physical page is out of the range of logical
                   pages which are allocated to the EMM handle.  The
                   program can recover from this condition by mapping a
                   logical page which is within the bounds for the EMM
                   handle.

               AH = 8Bh   RECOVERABLE.
                   One or more of the physical pages is out of the range of
                   allowable physical pages, or the log_phys_map_len
                   exceeds the number of mappable pages in the system.
                   Physical page numbers are numbered zero-relative.  The
                   program can recover from this condition by mapping into
                   memory at a physical page which is in the range of
                   supported physical pages.



          EMM Functions                                                 111





          Function 22. Alter Page Map & Jump



               AH = 8Fh   NON-RECOVERABLE.
                   The subfunction parameter is invalid.


          EXAMPLE

          log_phys_map              log_phys_map_struct (?) DUP (?)

          map_and_jump              map_and_jump_struct (?)

          emm_handle                          DW ?
          phys_page_or_seg_mode               DB ?

          MOV   AX,SEG map_and_jump
          MOV   DS,AX
          LEA   SI,map_and_jump               ; DS:SI points to
                                              ; map_and_jump
          MOV   DX,emm_handle
          MOV   AH,55h                        ; load function code
          MOV   AL,phys_page_or_seg_mode      ; specify physical page
                                              ; or segment mode
          INT   67h                           ; call memory manager
          OR    AH,AH                         ; check EMM status
          JNZ   emm_err_handler               ; jump to error handler on
                                              ; error
























          EMM Functions                                                 112





          Function 23. Alter Page Map & Call
          Alter Page Map & Call subfunction



          PURPOSE

               This subfunction saves the current memory mapping context,
               alters the specified memory mapping context, and transfers
               control to the specified address.  It is analogous to the
               FAR CALL in the 8086 family architecture.  Just as a return
               from a FAR CALL restores the original value in the code
               segment register, this subfunction restores the state of the
               specified mapping context after the return.

               There is no explicit expanded memory subfunction which
               emulates a return from a FAR CALL.  However, this facility
               is implicitly available through the standard return from a
               FAR CALL.  The following paragraphs describe how this works:

               After this function is invoked, unless an error is detected,
               the memory manager will transfer control to the address
               specified.  If an error occurs, the memory manager returns
               immediately with the error code in the AH register.
               Otherwise, the memory manager pushes on the stack informa-
               tion which enables it to restore the mapping context after
               the return.

               When the called procedure wants to return to the calling
               procedure, it simply issues a standard FAR RETURN.  The
               memory manager traps this return, restores the specified
               mapping context, and returns to the calling procedure.  The
               memory manager also returns a status from a successful
               return just as it does for all functions.

               Developers using this subfunction must make allowances for
               the additional stack space this subfunction will use.


          CALLING PARAMETERS

               AH = 56h
                   Contains the Alter Page Map & Call function.

                   log_phys_map_struct             STRUC
                       log_page_number             DW ?
                       phys_page_number_seg        DW ?
                   log_phys_map_struct             ENDS





          EMM Functions                                                 113





          Function 23. Alter Page Map & Call
          Alter Page Map & Call subfunction



                   map_and_call_struct             STRUC
                       target_address              DD ?
                       new_page_map_len            DB ?
                       new_page_map_ptr            DD ?
                       old_page_map_len            DB ?
                       old_page_map_ptr            DD ?
                       reserved                    DW 4 DUP (?)
                   map_and_call_struct             ENDS

               AL = physical page number/segment selector
                   Contains a code which indicates whether the value
                   contained in the

                       .new_page_map.phys_page_number_seg
                       .old_page_map.phys_page_number_seg

                   members are physical page numbers or are the segment
                   address representation of the physical page numbers.  A
                   value of zero in AL indicates that the values in these
                   members are physical page numbers.  A value of one in AL
                   indicates that the values in these members are the
                   segment address representations of the physical page
                   numbers.

               DX = handle number
                   Contains the EMM handle.

               DS:SI = pointer to map_and_call structure
                   Contains a pointer to a structure which contains the
                   information necessary to map the desired physical pages
                   and call the target address.  The structure members are
                   described here:

                   .target_address
                       The first member is a far pointer which contains the
                       target address to which control is to be trans-
                       ferred.  The address is represented in segment:of-
                       fset format.  The offset portion of the address is
                       stored in the low portion of the pointer.  The
                       application must supply this value.

                   .new_page_map_len
                       The second member is a byte which contains the
                       number of entries in the new mapping context to
                       which new_page_map_ptr points.  This number cannot
                       exceed the number of mappable pages in the system.


          EMM Functions                                                 114





          Function 23. Alter Page Map & Call
          Alter Page Map & Call subfunction



                   .new_page_map_ptr
                       The third member is a far pointer that points to an
                       array of structures which contains a list of the
                       logical page numbers and the physical page num-
                       bers/segments at which they are to be mapped im-
                       mediately after the call.  The contents of the new
                       array of structures are described at the end of the
                       map_and_call structure.

                   .old_page_map_len
                       The fourth member is a byte which contains the
                       number of entries in the old mapping context to
                       which old_page_map_ptr points.  This number cannot
                       exceed the number of mappable pages in the system.

                   .old_page_map_ptr
                       The fifth member is a far pointer that points to an
                       array of structures which contains a list of the
                       logical page numbers and the physical page num-
                       bers/segments at which they are to be mapped im-
                       mediately after the return.  The contents of the old
                       array of structures are described at the end of the
                       map_and_call structure.

                   .reserved
                       The sixth member is reserved for use by the memory
                       manager.

               Each entry in the old and new array of structures contains
               two elements:

                   .log_page_number
                       The first member of this structure is a word which
                       contains a logical page number which is to be mapped
                       at the succeeding physical page number/segment
                       immediately after the CALL (in the case of the new
                       array of structures) or after the RETURN (in the
                       case of the old array of structures).

                   .phys_page_number_seg
                       The second member of this structure is a word which
                       contains either the physical page number or the
                       segment address representation of the physical page
                       number/segment at which the preceding logical page
                       is to be mapped immediately after the CALL (in the
                       case of the new array of structures) or after the
                       RETURN (in the case of the old array of structures).

          EMM Functions                                                 115





          Function 23. Alter Page Map & Call
          Alter Page Map & Call subfunction



          REGISTERS MODIFIED

               AX

          Note............................................................
               Values in registers which don't contain required parameters
               maintain the values across the call.  The values in regis-
               ters (with the exception of AX) and the flag state at the
               beginning of the function are still in the registers and
               flags when the target address is reached.


          STATUS

               AH = 0   SUCCESSFUL.
                   Control has been transferred to the target address.

               AH = 80h   NON-RECOVERABLE.
                   The manager has detected a malfunction in the memory
                   manager software.

               AH = 81h   NON-RECOVERABLE.
                   The manager has detected a malfunction in the expanded
                   memory hardware.

               AH = 83h   NON-RECOVERABLE.
                   The manager couldn't find the specified EMM handle.  The
                   manager doesn't have any information pertaining to the
                   specified EMM handle.  The program may have corrupted
                   its EMM handle.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the manager is not defined.

               AH = 8Ah   RECOVERABLE.
                   One or more of the logical pages to map into a cor-
                   responding physical page is out of the range of logical
                   pages which are allocated to the EMM handle.  The
                   program can recover from this condition by mapping a
                   logical page which is within the bounds for the EMM
                   handle.







          EMM Functions                                                 116





          Function 23. Alter Page Map & Call
          Alter Page Map & Call subfunction



               AH = 8Bh   RECOVERABLE.
                   One or more of the physical pages is out of the range of
                   allowable physical pages, or you've specified more
                   physical pages than exist in the system.  Physical page
                   numbers are numbered zero-relative.  The program can
                   recover from this condition by mapping a physical page
                   which is in the range from zero to three.

               AH = 8Fh   NON-RECOVERABLE.
                   The subfunction parameter is invalid.


          EXAMPLE

          new_page_map              log_phys_map_struct (?) DUP (?)

          old_page_map              log_phys_map_struct (?) DUP (?)

          map_and_call              map_and_call_struct (?)

          emm_handle                DW ?
          phys_page_or_seg_mode     DB ?

          MOV   AX,SEG map_and_call
          MOV   DS,AX
          LEA   SI,map_and_call               ; DS:SI points to
                                              ; map_and_call
          MOV   DX,emm_handle                 ; specify EMM handle
          MOV   AH,56h                        ; load function code
          MOV   AL,phys_page_or_seg_mode      ; specify physical page
                                              ; or segment mode
          INT   67h                           ; control is actually
                                              ; transferred to the called
                                              ; procedure at this point
          OR    AH,AH                         ; check EMM status
          JNZ   emm_err_handler               ; jump to error handler on
                                              ; error











          EMM Functions                                                 117





          Function 23. Alter Page Map & Call
          Get Page Map Stack Space Size subfunction



          PURPOSE

               Since the Alter Page Map & Call function pushes additional
               information onto the stack, this subfunction returns the
               number of bytes of stack space the function requires.


          CALLING PARAMETERS

               AX = 5602h
                   Contains the Get Page Map Stack Space Size subfunction.


          RESULTS

               These results are valid only if the status returned is zero.

               BX = stack space required
                   Contains the number of bytes which the Alter Page Map &
                   Call function will require.  In other words, BX contains
                   the number (including the return address) which has to
                   be added to the stack pointer to remove all elements
                   from the stack.


          REGISTERS MODIFIED

               AX, BX


          STATUS

               AH = 0   SUCCESSFUL.
                   The size of the array has been returned.

               AH = 80h   NON-RECOVERABLE.
                   The manager has detected a malfunction in the memory
                   manager software.

               AH = 81h   NON-RECOVERABLE.
                   The manager has detected a malfunction in the expanded
                   memory hardware.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the manager is not defined.



          EMM Functions                                                 118





          Function 23. Alter Page Map & Call
          Get Page Map Stack Space Size subfunction



               AH = 8Fh   NON-RECOVERABLE.
                   The subfunction parameter is invalid.


          EXAMPLE

          stack_space_reqd               DW ?

          MOV   AX,5602h                 ; load function code
          INT   67h                      ; call the memory manager
          OR    AH,AH                    ; check EMM status
          JNZ   emm_err_handler          ; jump to error handler on error
          MOV   stack_space_reqd,BX      ; save required stack size count



































          EMM Functions                                                 119





          Function 24. Move/Exchange Memory Region
          Move Memory Region subfunction



          PURPOSE

               This subfunction copies a region of memory in the following
               memory source/destination combinations.

               o   conventional memory to conventional memory

               o   conventional memory to expanded memory

               o   expanded memory to conventional memory

               o   expanded memory to expanded memory

               You do not have to save and restore the expanded memory
               mapping context to perform these move operations.  The
               current mapping context is maintained throughout this
               operation.

               The length of the region is limited by the amount of
               expanded memory allocated to the handles specified.
               However, in most practical applications, the region length
               will be considerably smaller.  A region length of zero is
               not an error, and no move will be performed.

               A region length which exceeds 16K bytes is not an error.  In
               this case the function assumes that a group of logical pages
               is the target for the move.  The logical page specified
               represents the first logical page in which the move will
               take place.  If the region length exceeds 16K bytes, or if
               the region is less than 16K bytes but spans logical pages,
               there must be sufficient logical pages remaining after the
               first logical page for the entire region to fit.

               If your application needs to save a region of conventional
               memory in expanded memory, you can move it without having to
               perform a save or restore of the current mapping context.
               The memory manager maintains the context.  A move of up to
               1M bytes may be performed, although practical lengths are
               substantially less than this value.

               If the source and destination handles are identical, the
               source and destination regions are tested for overlap before
               the move.  If they overlap, the move direction is chosen so
               that the destination region receives an intact copy of the
               source region.  A status will be returned indicating that
               this overlap has occurred.


          EMM Functions                                                 120





          Function 24. Move/Exchange Memory Region
          Move Memory Region subfunction



          CALLING PARAMETERS

               AX = 5700h
                   Contains the Move Memory Region function.

                   move_source_dest_struct         STRUC
                       region_length               DD ?
                       source_memory_type          DB ?
                       source_handle               DW ?
                       source_initial_offset       DW ?
                       source_initial_seg_page     DW ?
                       dest_memory_type            DB ?
                       dest_handle                 DW ?
                       dest_initial_offset         DW ?
                       dest_initial_seg_page       DW ?
                   move_source_dest_struct         ENDS

               DS:SI = pointer to move_source_dest structure
                   Contains a pointer to a data structure which contains
                   the source and destination information for the move.
                   The structure members are described here:

                   .region_length
                       The first member is a double word which specifies
                       the length of the memory region (in bytes) to be
                       moved.

                   .source_memory_type
                       The second member is a byte which specifies the type
                       of memory where the source region resides.  A value
                       of zero indicates that the source region resides in
                       conventional memory (excluding the page frame seg-
                       ment).  A value of one indicates that the source
                       region resides in expanded memory.

                   .source_handle
                       If the source region resides in expanded memory, the
                       third member is a word which specifies the handle
                       number associated with the source memory region.  If
                       the source region resides in conventional memory,
                       this variable has no meaning and should be set to
                       zero for future compatibility.

                   .source_initial_offset
                       The fourth member is a word which specifies the
                       offset within the source region from which to begin
                       the move.

          EMM Functions                                                 121





          Function 24. Move/Exchange Memory Region
          Move Memory Region subfunction



                       If the source region resides in expanded memory, the
                       source_initial_offset is relative to the beginning
                       of the 16K logical page.  Because the offset is
                       relative to the beginning of a 16K expanded memory
                       page, it may only take on values between 0000h and
                       3FFFh.

                       If the source region resides in conventional memory,
                       the source_initial_offset is a word which specifies
                       the offset, relative to the beginning of the source
                       segment, from which to begin the move.  Because the
                       offset is relative to the beginning of a 64K-byte
                       conventional memory segment, it may take on values
                       between 0000h and FFFFh.

                   .source_initial_seg_page
                       The fifth member is a word which specifies the
                       initial segment or logical page number within the
                       source region from which to begin the move.

                       If the source region resides in expanded memory, the
                       value specifies the logical page within the source
                       region from which to begin the move.

                       If the source region resides in conventional memory,
                       the source_initial_seg_page specifies the initial
                       segment address within conventional memory from
                       which to begin the move.

                   .dest_memory_type
                       The sixth member is a byte which specifies the type
                       of memory where the destination region resides.  A
                       value of zero indicates conventional memory; a value
                       of one indicates expanded memory.

                   .dest_handle
                       If the destination region resides in expanded
                       memory, the seventh member is a word which specifies
                       the handle number associated with the destination
                       memory region.  If the destination region resides in
                       conventional memory, this variable has no meaning
                       and should be set to zero for future compatibility.

                   .dest_initial_offset
                       The eighth member is a word which specifies the
                       offset within the destination region from which to
                       begin the move.

          EMM Functions                                                 122





          Function 24. Move/Exchange Memory Region
          Move Memory Region subfunction



                       If the destination region resides in expanded
                       memory, the dest_initial_offset is relative to the
                       beginning of the 16K-byte logical page.  Because the
                       offset is relative to the beginning of a 16K-byte
                       expanded memory page, it may only take on values
                       between 0000h and 3FFFh.

                       If the destination region resides in conventional
                       memory, the dest_initial_offset is a word which
                       specifies the offset, relative to the beginning of
                       the destination segment, to begin the move.  Because
                       the offset is relative to the beginning of a 64K
                       conventional memory segment, it may take on values
                       between 0000h and FFFFh.

                   .dest_initial_seg_page
                       The ninth member is a word which specifies the
                       initial segment or logical page number within the
                       destination region from which to begin the move.

                       If the destination region resides in expanded memory
                       then the value specifies the logical page within the
                       destination region from which to begin the move.

                       If the destination region resides in conventional
                       memory, the dest_initial_seg_page specifies the
                       initial segment address within conventional memory
                       from which to begin the move.


          REGISTERS MODIFIED

               AX


          STATUS

               AH = 0   SUCCESSFUL.
                   The memory regions have been moved.

               AH = 80h   NON-RECOVERABLE.
                   The manager has detected a malfunction in the memory
                   manager software.

               AH = 81h   NON-RECOVERABLE.
                   The manager has detected a malfunction in the expanded
                   memory hardware.

          EMM Functions                                                 123





          Function 24. Move/Exchange Memory Region
          Move Memory Region subfunction



               AH = 83h   NON-RECOVERABLE.
                   The manager couldn't find either the source or destina-
                   tion EMM handles.  The memory manager doesn't have any
                   information on the handles specified.  The program may
                   have corrupted its EMM handles.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the manager is not defined.

               AH = 8Ah   NON-RECOVERABLE.
                   One or more of the logical pages is out of the range of
                   logical pages allocated to the source/destination
                   handle.

               AH = 8Fh   NON-RECOVERABLE.
                   The subfunction parameter is invalid.

               AH = 92h   SUCCESSFUL.
                   The source and destination expanded memory regions have
                   the same handle and overlap.  This is valid for a move.
                   The move has been completed and the destination region
                   has a full copy of the source region.  However, at least
                   a portion of the source region has been overwritten by
                   the move.  Note that the source and destination expanded
                   memory regions with different handles will never physi-
                   cally overlap because the different handles specify
                   totally different regions of expanded memory.

               AH = 93h   CONDITIONALLY-RECOVERABLE.
                   The length of the source or destination expanded memory
                   region specified exceeds the length of the expanded
                   memory region allocated either the source or destination
                   handle.  Insufficient pages are allocated to this handle
                   to move a region of the size specified.  The program can
                   recover from this condition by allocating additional
                   pages to the destination or source handle and attempting
                   to execute the function again.  However, if the applica-
                   tion program allocated as much expanded memory as it
                   thought it needed, this may be a program error and is
                   not recoverable.

               AH = 94h   NON-RECOVERABLE.
                   The conventional memory region and expanded memory
                   region overlap.  This is invalid, the conventional
                   memory region cannot overlap the expanded memory region.



          EMM Functions                                                 124





          Function 24. Move/Exchange Memory Region
          Move Memory Region subfunction



               AH = 95h   NON-RECOVERABLE.
                   The offset within the logical page exceeds the length of
                   the logical page.  The initial source or destination
                   offsets within an expanded memory region must be between
                   0000h and 3FFFh (16383 or (length of a logical page
                   - 1)).

               AH = 96h   NON-RECOVERABLE.
                   Region length exceeds 1M bytes.

               AH = 98h   NON-RECOVERABLE.
                   The memory source and destination types are undefined.

               AH = A2h   NON-RECOVERABLE.
                   An attempt was made to wrap around the 1M-byte address
                   space of conventional memory during the move.  The
                   combination of source/destination starting address and
                   length of the region to be moved exceeds 1M bytes.  No
                   data was moved.


          EXAMPLE

          move_source_dest               move_source_dest_struct (?)

          MOV   AX,SEG move_source_dest
          MOV   DS,AX
          LEA   SI,move_source_dest      ; DS:SI points to move_source_dest
          MOV   AX,5700h                 ; load function code
          INT   67h                      ; call the memory manager
          OR    AH,AH                    ; check EMM status
          JNZ   emm_err_handler          ; jump to error handler on error
















          EMM Functions                                                 125





          Function 24. Move/Exchange Memory Region
          Exchange Memory Region subfunction



          PURPOSE

               This subfunction exchanges (using a string move) a region of
               memory in any of the following memory source/destination
               combinations.

               o   conventional memory to conventional memory

               o   conventional memory to expanded memory

               o   expanded memory to conventional memory

               o   expanded memory to expanded memory

               The term expanded memory region refers only to the area of
               memory above 640K bytes (9FFFFh).  If a system provides
               mappable conventional memory, this function treats the
               mappable conventional memory regions as ordinary convention-
               al memory.  The contents of the source region and the
               destination region are exchanged.

               The exchange operation can be performed without having to
               save and restore the expanded memory mapping context.  The
               current mapping context is maintained throughout this
               operation.  The length of the region is limited to the
               amount of expanded memory allocated to the specified EMM
               handles.  A length of zero is not an error; however, no
               exchange will be performed.  A region length which exceeds
               16K bytes is not an error.  In this case the function
               assumes that a group of logical pages is the target for the
               exchange.  The logical page specified represents the first
               logical page in which the exchange will take place.  If the
               region length exceeds 16K bytes, or if the region is less
               than 16K bytes but spans logical pages, there must be
               sufficient logical pages remaining after the first logical
               page for the entire region to fit.

               If your application needs to exchange a region of conven-
               tional memory with expanded memory, you can simply exchange
               it with the region of interest without having to perform a
               save or restore of the current mapping context.  An exchange
               of up to 1M bytes may be performed, although practical
               lengths are obviously below that value.  Checking is done
               before starting the exchange to prevent the possibility of
               overlap during the exchange operation.  Overlapping source
               and destination regions for an exchange are invalid, and the
               exchange will not take place.

          EMM Functions                                                 126





          Function 24. Move/Exchange Memory Region
          Exchange Memory Region subfunction



          CALLING PARAMETERS

               AX = 5701h
                   Contains the Exchange Memory Region function.

                   xchg_source_dest_struct         STRUC
                       region_length               DD ?
                       source_memory_type          DB ?
                       source_handle               DW ?
                       source_initial_offset       DW ?
                       source_initial_seg_page     DW ?
                       dest_memory_type            DB ?
                       dest_handle                 DW ?
                       dest_initial_offset         DW ?
                       dest_initial_seg_page       DW ?
                   xchg_source_dest_struct         ENDS

               DS:SI = pointer to xchg_source_dest structure
                   Contains a pointer to the data structure which contains
                   the source and destination information for the exchange.
                   The structure members are described here:

                   .region_length
                       The first member is a double word which specifies
                       the length of the memory region to be exchanged.

                   .source_memory_type
                       The second member is a byte which specifies the type
                       of memory where the source region resides.  A value
                       of zero indicates that the source region resides in
                       conventional memory.  A value of one indicates that
                       the source region resides in expanded memory.

                   .source_handle
                       If the source region resides in expanded memory, the
                       third member is a word which specifies the handle
                       number associated with the source memory region.  If
                       the source region resides in conventional memory,
                       this variable has no meaning and should be set to
                       zero for future compatibility.

                   .source_initial_offset
                       The fourth member is a word which specifies the
                       offset within the source region from which to begin
                       the exchange.



          EMM Functions                                                 127





          Function 24. Move/Exchange Memory Region
          Exchange Memory Region subfunction



                       If the source region resides in expanded memory, the
                       source_initial_offset is relative to the beginning
                       of the 16K logical page.  Because the offset is
                       relative to the beginning of a 16K expanded memory
                       page, it may only take on values between 0000h and
                       3FFFh.

                       If the source region resides in conventional memory,
                       the source_initial_offset is a word which specifies
                       the offset, relative to the beginning of the source
                       segment, from which to begin the exchange at.
                       Because the offset is relative to the beginning of a
                       64K-byte conventional memory segment, it may take on
                       values between 0000h and FFFFh.

                   .source_initial_seg_page
                       The fifth member is a word which specifies the
                       initial segment or logical page number within the
                       source region from which to begin the exchange.

                       If the source region resides in expanded memory then
                       the value specifies the logical page within the
                       source region from which to begin the exchange.

                       If the source region resides in conventional memory,
                       the source_initial_seg_page specifies the initial
                       segment address within conventional memory from
                       which to begin the exchange.

                   .dest_memory_type
                       The sixth member is a byte which specifies the type
                       of memory where the destination region resides.  A
                       value of zero indicates that the destination region
                       resides in conventional memory (excluding the page
                       frame segment).  A value of one indicates that the
                       destination region resides in expanded memory.

                   .dest_handle
                       If the destination region resides in expanded
                       memory, the seventh member is a word which specifies
                       the handle number associated with the destination
                       memory region.  If the destination region resides in
                       conventional memory, this variable has no meaning
                       and should be set to zero for future compatibility.




          EMM Functions                                                 128





          Function 24. Move/Exchange Memory Region
          Exchange Memory Region subfunction



                   .dest_initial_offset
                       The eighth member is a word which specifies the
                       offset within the destination region from which to
                       begin the exchange.

                       If the destination region resides in expanded
                       memory, the dest_initial_offset is relative to the
                       beginning of the 16K-byte logical page.  Because the
                       offset is relative to the beginning of a 16K-byte
                       expanded memory page, it may only take on values
                       between 0000h and 3FFFh.

                       If the destination region resides in conventional
                       memory, the dest_initial_offset is a word which
                       specifies the offset, relative to the beginning of
                       the destination segment, to begin the exchange at.
                       Because the offset is relative to the beginning of a
                       64K conventional memory segment, it may take on
                       values between 0000h and FFFFh.

                   .dest_initial_seg_page
                       The ninth member is a word which specifies the
                       initial segment or logical page number within the
                       destination region from which to begin the exchange.

                       If the destination region resides in expanded memory
                       then the value specifies the logical page within the
                       destination region from which to begin the exchange.

                       If the destination region resides in conventional
                       memory, the dest_initial_seg_page specifies the
                       initial segment address within conventional memory
                       from which to begin the exchange.



          REGISTERS MODIFIED

               AX


          STATUS

               AH = 0   SUCCESSFUL.
                   The memory regions have been exchanged.



          EMM Functions                                                 129





          Function 24. Move/Exchange Memory Region
          Exchange Memory Region subfunction



               AH = 80h   NON-RECOVERABLE.
                   The manager has detected a malfunction in the memory
                   manager software.

               AH = 81h   NON-RECOVERABLE.
                   The manager has detected a malfunction in the expanded
                   memory hardware.

               AH = 83h   NON-RECOVERABLE.
                   The manager could not find either the source or destina-
                   tion EMM handles.  The memory manager does not currently
                   have any information pertaining to the handles speci-
                   fied.  The program may have corrupted its EMM handles.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the manager is not defined.

               AH = 8Ah   NON-RECOVERABLE.
                   One or more of the logical pages is out of the range of
                   logical pages allocated to the source/destination
                   handle.

               AH = 8Fh   NON-RECOVERABLE.
                   The subfunction parameter is invalid.

               AH = 93h   CONDITIONALLY-RECOVERABLE.
                   The length of the source or destination expanded memory
                   region specified, exceeds the length of the expanded
                   memory region allocated to the source or destination
                   specified EMM handle.  There are insufficient pages
                   allocated to this handle to exchange a region of the
                   size specified.  The program can recover from this
                   condition by attempting to allocate additional pages to
                   the destination or source handle and attempting to
                   execute the function again.  However, if the application
                   program was allocated as much expanded memory as it
                   thought it needed, this may be a program error and is
                   therefore not recoverable.

               AH = 94h   NON-RECOVERABLE.
                   The conventional memory region and expanded memory
                   region overlap.  This is invalid, the conventional
                   memory region cannot overlap the expanded memory region.





          EMM Functions                                                 130





          Function 24. Move/Exchange Memory Region
          Exchange Memory Region subfunction



               AH = 95h   NON-RECOVERABLE.
                   The offset within the logical page exceeds the length of
                   the logical page.  The initial source or destination
                   offsets within an expanded memory region must be between
                   0000h and 3FFFh (16383 or (length of a logical page
                   - 1)).

               AH = 96h   NON-RECOVERABLE.
                   Region length exceeds 1M-byte limit.

               AH = 97h   NON-RECOVERABLE.
                   The source and destination expanded memory regions have
                   the same handle and overlap.  This is invalid, the
                   source and destination expanded memory regions cannot
                   have the same handle and overlap when they are being
                   exchanged.  Note that the source and destination
                   expanded memory regions which have different handles
                   will never physically overlap because the different
                   handles specify totally different regions of expanded
                   memory.

               AH = 98h   NON-RECOVERABLE.
                   The memory source and destination types are undefined.

               AH = A2h   NON-RECOVERABLE.
                   An attempt was made to wrap around the 1M-byte address
                   space of conventional memory during the exchange.  The
                   combination of source/destination starting address and
                   length of the region to be exchanged exceeds 1M bytes.
                   No data was exchanged.


          EXAMPLE

          xchg_source_dest               xchg_source_dest_struct (?)

          MOV   AX,SEG xchg_source_dest
          MOV   DS,AX
          LEA   SI,xchg_source_dest      ; DS:SI points to xchg_source_dest
          MOV   AX,5701h                 ; load function code
          INT   67h                      ; call the memory manager
          OR    AH,AH                    ; check EMM status
          JNZ   emm_err_handler          ; jump to error handler on error





          EMM Functions                                                 131





          Function 25. Get Mappable Physical Address Array
          Get Mappable Physical Address Array subfunction



          PURPOSE

               This subfunction returns an array containing the segment
               address and physical page number for each mappable physical
               page in a system.  The contents of this array provide a
               cross reference between physical page numbers and the actual
               segment addresses for each mappable page in the system.  The
               array is sorted in ascending segment order.  This does not
               mean that the physical page numbers associated with the
               segment addresses are also in ascending order.


          CALLING PARAMETERS

               AX = 5800h
                   Contains the Get Mappable Physical Address Array
                   subfunction

                   mappable_phys_page_struct       STRUC
                       phys_page_segment           DW ?
                       phys_page_number            DW ?
                   mappable_phys_page_struct       ENDS

               ES:DI = mappable_phys_page
                   Contains a pointer to an application-supplied memory
                   area where the memory manager will copy the physical
                   address array.  Each entry in the array is a structure
                   containing two members:

                   .phys_page_segment
                       The first member is a word which contains the
                       segment address of the mappable physical page
                       associated with the physical page number following
                       it.  The array entries are sorted in ascending
                       segment address order.

                   .phys_page_number
                       The second member is a word which contains the
                       physical page number which corresponds to the
                       previous segment address.  The physical page numbers
                       are not necessarily in ascending order.







          EMM Functions                                                 132





          Function 25. Get Mappable Physical Address Array
          Get Mappable Physical Address Array subfunction



                   Example 1

                       An expanded memory board has its page frame starting
                       at address C0000h and has no mappable conventional
                       memory.  For this configuration, physical page 0
                       corresponds to segment address C000h, physical page
                       1 corresponds to segment address C400h, etc.  The
                       array would contain the following data (in this
                       order):

                       C000h, 00h
                       C400h, 01h
                       C800h, 02h
                       CC00h, 03h


                   Example 2

                       An expanded memory board has a large page frame
                       starting at address C0000h and has mappable conven-
                       tional memory from 90000h through 9FFFFh.  For this
                       configuration, physical page 0 corresponds to
                       segment address C000h, physical page 1 corresponds
                       to segment address C400h, etc.  The array would
                       contain the following data in the order specified.
                       Note that the expanded memory region always has the
                       lowest numerically valued physical page numbers.

                       9000h, 0Ch
                       9400h, 0Dh
                       9800h, 0Eh
                       9C00h, 0Fh
                       C000h, 00h
                       C400h, 01h
                       C800h, 02h
                       CC00h, 03h
                       D000h, 04h
                       D400h, 05h
                       D800h, 06h
                       DC00h, 07h
                       E000h, 08h
                       E400h, 09h
                       E800h, 0Ah
                       EC00h, 0Bh




          EMM Functions                                                 133





          Function 25. Get Mappable Physical Address Array
          Get Mappable Physical Address Array subfunction



          RESULTS

               These results are valid only if the status returned is zero.

               CX = number of entries in the mappable_phys_page
                   Multiply this number by (SIZE mappable_phys_page_struct)
                   to determine the number of bytes the physical page
                   address array requires.


          REGISTERS MODIFIED

               AX, CX


          STATUS

               AH = 0   SUCCESSFUL.
                   The hardware configuration array has been returned.

               AH = 80h   NON-RECOVERABLE.
                   The manager has detected a malfunction in the memory
                   manager software.

               AH = 81h   NON-RECOVERABLE.
                   The manager has detected a malfunction in the expanded
                   memory hardware.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the manager is not defined.

               AH = 8Fh   NON-RECOVERABLE.
                   The subfunction parameter is invalid.















          EMM Functions                                                 134





          Function 25. Get Mappable Physical Address Array
          Get Mappable Physical Address Array subfunction



          EXAMPLE

          mappable_phys_page             mappable_phys_page_struct (?)

          mappable_page_entry_count      DW ?

          MOV   AX,SEG mappable_phys_page
          MOV   ES,AX
          LEA   DI,mappable_phys_page         ; ES:DI points to
                                              ; mappable_phys_page
          MOV   AX,5800h                      ; load function code
          INT   67h                           ; call the memory
                                              ; manager
          OR    AH,AH                         ; check EMM status
          JNZ   emm_err_handler               ; jump to error handler
                                              ; on error
          MOV   mappable_page_entry_count,CX  ; save mappable
                                              ; page entry count






























          EMM Functions                                                 135





          Function 25. Get Mappable Physical Address Array
          Get Mappable Physical Address Array Entries subfunction



          PURPOSE

               This subfunction gets the number of entries which will be
               required for the array the first subfunction returns.


          CALLING PARAMETERS

               AX = 5801h
                   Contains the Get Physical Page Address Array Entries
                   subfunction.  This subfunction returns a word which
                   represents the number of entries in the array returned
                   by the previous subfunction.  This number also repre-
                   sents the number of mappable physical pages in a system.


          RESULTS

               These results are valid only if the status returned is zero.

               CX = number of entries in the mappable_phys_page
                   Multiply this number by (SIZE mappable_phys_page_struct)
                   to determine the number of bytes the physical page
                   address array will require.


          REGISTERS MODIFIED

               AX, CX


          STATUS

               AH = 0   SUCCESSFUL.
                   The number of mappable physical pages has been returned.

               AH = 80h   NON-RECOVERABLE.
                   The manager has detected a malfunction in the memory
                   manager software.

               AH = 81h   NON-RECOVERABLE.
                   The manager has detected a malfunction in the expanded
                   memory hardware.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the manager is not defined.


          EMM Functions                                                 136





          Function 25. Get Mappable Physical Address Array
          Get Mappable Physical Address Array Entries subfunction



               AH = 8Fh   NON-RECOVERABLE.
                   The subfunction parameter is invalid.


          EXAMPLE

          mappable_page_entry_count           DW ?

          MOV   AX,5801h                      ; load function code
          INT   67h                           ; call memory manager
          OR    AH,AH                         ; check EMM status
          JNZ   emm_err_handler               ; jump to error handler
                                              ; on error
          MOV   mappable_page_entry_count,CX  ; save mappable
                                              ; page entry count

































          EMM Functions                                                 137





          Function 26. Get Expanded Memory Hardware Information
          Get Hardware Configuration Array subfunction



          Note............................................................
               This function is for use by operating systems only.  This
               function can be disabled at any time by the operating
               system.  Refer to Function 30 for a description of how an
               operating system does this.


          PURPOSE

               This subfunction returns an array containing expanded memory
               hardware configuration information for use by an operating
               system/environment.


          CALLING PARAMETERS

               AX = 5900h
                   Contains the Get Hardware Configuration Array subfunc-
                   tion.

                   hardware_info_struct            STRUC
                       raw_page_size               DW ?
                       alternate_register_sets     DW ?
                       context_save_area_size      DW ?
                       DMA_register_sets           DW ?
                       DMA_channel_operation       DW ?
                   hardware_info_struct            ENDS

               ES:DI = hardware_info
                   Contains a pointer to a memory area that the operating
                   system supplies where the memory manager will copy
                   expanded memory hardware information.  The structure
                   contains these five members:

                   .raw_page_size
                       The first member is a word which contains the size
                       of a raw mappable physical page in paragraphs (16
                       bytes).  LIM standard pages are always 16K bytes.
                       However, other implementations of expanded memory
                       boards do not necessarily comply with this standard
                       and can emulate a 16K-byte page by mapping in
                       multiple smaller pages.  This member specifies the
                       size of a mappable physical page viewed from the
                       hardware implementation level.




          EMM Functions                                                 138





          Function 26. Get Expanded Memory Hardware Information
          Get Hardware Configuration Array subfunction



                   .alternate_register_sets
                       The second member is a word which specifies the
                       number of alternate mapping register sets.  The
                       additional mapping register sets are termed alter-
                       nate mapping register sets in this document.

                       All expanded memory boards have at least one set of
                       hardware registers to perform the logical to
                       physical page mapping.  Some expanded memory boards
                       have more than one set of these mapping registers.
                       This member specifies how many of these alternate
                       mapping register sets exist (beyond the one set that
                       all expanded memory boards have) on the expanded
                       memory boards in the system.  If an expanded memory
                       card has only one set of mapping registers (that is,
                       no alternate mapping register sets) this member has
                       a value of zero.

                   .context_save_area_size
                       The third member is a word which contains the
                       storage requirements for the array required to save
                       a mapping context.  The value returned in this
                       member is exactly the same as that returned by
                       Function 15 (Get Size of Page Map Save Array
                       subfunction).

                   .DMA_register_sets
                       The fourth member is a word which contains the
                       number of register sets that can be assigned to DMA
                       channels.  These DMA register sets, although similar
                       in use to alternate register sets, are for DMA
                       mapping and not task mapping.

                       If the expanded memory hardware does not support DMA
                       register sets, care must be taken when DMA is taking
                       place.

                       In a multitasking operating system, when one task is
                       waiting for DMA to complete, it is useful to be able
                       to switch to another task.  However, if the DMA is
                       taking place in memory that the second task will
                       need to remap, remapping would be disastrous.






          EMM Functions                                                 139





          Function 26. Get Expanded Memory Hardware Information
          Get Hardware Configuration Array subfunction



                       If the expanded memory hardware can detect when DMA
                       is occurring, the OS/E should allow task switches
                       and remapping during DMA.  If no special support for
                       DMA is available, no remapping should be done when
                       DMA is in progress.

                   .DMA_channel_operation
                       The fifth member is a word which specifies a special
                       case for the DMA register sets.  A value of zero
                       specifies that the DMA register sets behave as
                       described in Function 28.  A value of one specifies
                       that the expanded memory hardware has only one DMA
                       register set.  In addition, if any channel is mapped
                       through this register set, then all channels are
                       mapped through it.  For LIM standard boards, this
                       value is zero.


          RESULTS

               These results are valid only if the status returned is zero.

               hardware_info
                   Contains the expanded memory hardware-specific informa-
                   tion described above.


          REGISTERS MODIFIED

               AX


          STATUS

               AH = 0   SUCCESSFUL.
                   The hardware configuration array has been returned.

               AH = 80h   NON-RECOVERABLE.
                   The manager has detected a malfunction in the memory
                   manager software.

               AH = 81h   NON-RECOVERABLE.
                   The manager has detected a malfunction in the expanded
                   memory hardware.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the manager is not defined.

          EMM Functions                                                 140





          Function 26. Get Expanded Memory Hardware Information
          Get Hardware Configuration Array subfunction



               AH = 8Fh   NON-RECOVERABLE.
                   The subfunction parameter is invalid.

               AH = A4h   NON-RECOVERABLE.
                   Access to this function has been denied by the operating
                   system.  The function cannot be used at this time.


          EXAMPLE

          hardware_info                  hardware_info_struct (?)

          MOV   AX,SEG hardware_info
          MOV   ES,AX
          LEA   DI,hardware_info         ; ES:DI points to hardware_info
          MOV   AX,5900h                 ; load function code
          INT   67h                      ; call the memory manager
          OR    AH,AH                    ; check EMM status
          JNZ   emm_err_handler          ; jump to error handler on error





























          EMM Functions                                                 141





          Function 26. Get Expanded Memory Hardware Information
          Get Unallocated Raw Page Count subfunction



          PURPOSE

               The Get Unallocated Raw Page Count subfunction returns the
               number of unallocated non-standard length mappable pages as
               well as the total number of non-standard length mappable
               pages in expanded memory to the operating system.

               One variety of expanded memory board has a page size which
               is a sub-multiple of 16K bytes.  An expanded memory page
               which is a sub-multiple of 16K is termed a raw page.  An
               operating system may deal with mappable physical page sizes
               which are sub-multiples of 16K bytes.

               If the expanded memory board supplies pages in exact
               multiples of 16K bytes, the number of pages this function
               returns is identical to the number Function 3 (Get Unallo-
               cated Page Count) returns.  In this case, there is no
               difference between a page and a raw page.


          CALLING PARAMETERS

               AX = 5901h
                   Contains the Get Unallocated Raw Page Count subfunction.


          RESULTS

               These results are valid only if the status returned is zero.

               BX = unallocated raw pages
                   The number of raw pages that are currently available for
                   use.

               DX = total raw pages
                   The total number of raw pages in expanded memory.


          REGISTERS MODIFIED

               AX, BX, DX







          EMM Functions                                                 142





          Function 26. Get Expanded Memory Hardware Information
          Get Unallocated Raw Page Count subfunction



          STATUS

               AH = 0   SUCCESSFUL.
                   The manager has returned the number of unallocated raw
                   pages and the number of total raw pages in expanded
                   memory.

               AH = 80h   NON-RECOVERABLE.
                   The manager detected a malfunction in the memory manager
                   software.

               AH = 81h   NON-RECOVERABLE.
                   The manager detected a malfunction in the expanded
                   memory hardware.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the memory manager is not
                   defined.

               AH = 8Fh   NON-RECOVERABLE.
                   The subfunction parameter is invalid.


          EXAMPLE

          unalloc_raw_pages              DW ?
          total_raw_pages                DW ?

          MOV   AX,5901h                 ; load function code
          INT   67h                      ; call the memory manager
          OR    AH,AH                    ; check EMM status
          JNZ   emm_err_handler          ; jump to error handler on error
          MOV   unalloc_raw_pages,BX     ; save unallocated raw page count
          MOV   total_raw_pages,DX       ; save total raw page count














          EMM Functions                                                 143





          Function 27. Allocate Standard/Raw Pages
          Allocate Standard Pages subfunction



          PURPOSE

               The Allocate Standard Pages subfunction allocates the number
               of standard size (16K bytes) pages that the operating system
               requests and assigns a unique EMM handle to these pages.
               The EMM handle owns these pages until the operating system
               deallocates them.  This subfunction allows you to allocate
               zero pages to a handle, unlike Function 4 (Allocate Pages).

          Note............................................................
               This note affects expanded memory manager implementors and
               operating system developers only.  Applications should not
               use the following characteristic of the memory manager.  An
               application violating this rule will be incompatible with
               future versions of Microsoft's operating systems and
               environments.

               To be compatible with this specification, an expanded memory
               manager will provide a special handle which is available to
               the operating system only.  This handle will have a value of
               0000h and will have a set of pages allocated to it when the
               expanded memory manager driver installs.  The pages that the
               memory manager will automatically allocate to handle 0000h
               are those that backfill conventional memory.  Typically,
               this backfill occurs between addresses 40000h (256K) and
               9FFFFh (640K).  However, the range can extend below and
               above this limit if the hardware and memory manager have the
               capability.

               An operating system won't have to invoke Function 27 to
               obtain this handle because it can assume the handle already
               exists and is available for use immediately after the
               expanded memory device driver installs.  When an operating
               system wants to use this handle, it uses the special handle
               value of 0000h.  The operating system will be able to invoke
               any EMM function using this special handle value.  To
               allocate pages to this handle, the operating system need
               only invoke Function 18 (Reallocate Pages).

               There are two special cases for this handle:

               1.  Function 27 (Allocate Standard Pages subfunction).  This
                   function must never return zero as a handle value.
                   Applications must always invoke Function 27 to allocate
                   pages and obtain a handle which identifies the pages
                   which belong to it.  Since Function 27 never returns a


          EMM Functions                                                 144





          Function 27. Allocate Standard/Raw Pages
          Allocate Standard Pages subfunction



                   handle value of zero, an application will never gain
                   access to this special handle.

               2.  Function 6 (Deallocate Pages).  If the operating system
                   uses it to deallocate the pages which are allocated to
                   this handle, the pages the handle owns will be returned
                   to the manager for use.  But the handle will not be
                   available for reassignment.  The manager should treat a
                   deallocate pages function request for this handle the
                   same as a reallocate pages function request, where the
                   number of pages to reallocate to this handle is zero.


          CALLING PARAMETERS

               AX = 5A00h
                   Contains the Allocate Standard Pages subfunction.

               BX = num_of_standard_pages_to_alloc
                   Contains the number of standard pages the operating
                   system wants to allocate.


          RESULTS

               These results are valid only if the status returned is zero.

               DX = handle
                   Contains a unique EMM handle.  The operating system must
                   use this EMM handle as a parameter in any function that
                   requires it.  Up to 255 handles may be obtained.  (Both
                   Function 27 and Function 4 must share the same 255
                   handles.)

                   For all functions using this handle, the length of the
                   physical and logical pages allocated to it are standard
                   length (that is, 16K bytes).


          REGISTERS MODIFIED

               AX, DX






          EMM Functions                                                 145





          Function 27. Allocate Standard/Raw Pages
          Allocate Standard Pages subfunction



          STATUS

               AH = 0   SUCCESSFUL.
                   The manager has allocated the pages to an assigned EMM
                   standard handle.

               AH = 80h   NON-RECOVERABLE.
                   The manager detected a malfunction in the memory manager
                   software.

               AH = 81h   NON-RECOVERABLE.
                   The manager detected a malfunction in the expanded
                   memory hardware.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the memory manager is not
                   defined.

               AH = 85h   RECOVERABLE.
                   All EMM handles are being used.

               AH = 87h   RECOVERABLE.
                   There aren't enough expanded memory pages present in the
                   system to satisfy the operating system's request.

               AH = 88h   RECOVERABLE.
                   There aren't enough unallocated pages to satisfy the
                   operating system's request.

               AH = 8Fh   NON-RECOVERABLE.
                   The subfunction parameter is invalid.


          EXAMPLE

          num_of_standard_pages_to_alloc      DW ?
          emm_handle                          DW ?

          MOV   BX,num_of_standard_pages_to_alloc
          MOV   AX,5A00h                      ; load function code
          INT   67h                           ; call the memory manager
          OR    AH,AH                         ; check EMM status
          JNZ   emm_err_handler               ; jump to error handler on
                                              ; error
          MOV   emm_handle,DX                 ; save handle



          EMM Functions                                                 146





          Function 27. Allocate Standard/Raw Pages
          Allocate Raw Pages subfunction



          PURPOSE

               The Allocate Raw Pages function allocates the number of non-
               standard size pages that the operating system requests and
               assigns a unique EMM handle to these pages.  The EMM handle
               owns these pages until the operating system deallocates
               them.  This function allows you to allocate zero pages to a
               handle, unlike Function 4 (Allocate Pages).

               A hardware vendor may design an expanded memory board that
               has a page size which is a sub-multiple of 16K bytes.  A
               physical page which is a sub-multiple of 16K is termed a raw
               page.  The operating system may deal with page sizes which
               are sub-multiples of 16K bytes.  The memory manager must
               treat any function using a handle with raw pages allocated
               to it by Function 27 (Allocate Raw Pages subfunction)
               differently than it does a handle that has normal 16K-byte
               pages allocated to it.

               Handles which are assigned using Function 4 (Allocate Pages)
               or Function 27 (Allocate Standard Pages subfunction) must
               have pages which are 16K bytes -- this is the length of a
               standard expanded memory page.  If the expanded memory board
               hardware is not able to supply 16K-byte pages, the memory
               manager must emulate pages which are 16K bytes combining
               multiple non-standard size pages to form a single 16K-byte
               page.

               Handles which are assigned using Function 27 (Allocate Raw
               Pages subfunction) are called raw handles.  All logical
               pages allocated to a raw handle may have a non-standard
               length (that is, not 16K bytes).  However, once the operat-
               ing system has allocated a number of raw pages to a handle,
               it is the responsibility of the memory manager to recognize
               that raw handle as one that has non-standard size pages
               allocated to it.  The memory manager must identify these
               handles and treat all functions which use handles which have
               non-standard page lengths differently.  The logical page
               length becomes the length of the non-standard size page for
               any raw handle that Function 27 assigns.

          Note............................................................
               This note affects expanded memory manager implementors and
               operating system developers only.  Applications should not
               use the following characteristic of the memory manager.  An
               application violating this rule will be incompatible with


          EMM Functions                                                 147





          Function 27. Allocate Standard/Raw Pages
          Allocate Raw Pages subfunction



               future versions of Microsoft's operating systems and
               environments.

               To be compatible with this specification, an expanded memory
               manager will provide a special handle which is available to
               the operating system only.  This handle will have a value of
               0000h and will have a set of pages allocated to it when the
               expanded memory manager driver installs.  The pages that the
               memory manager will automatically allocate to handle 0000h
               are those that backfill conventional memory.  Typically,
               this backfill occurs between addresses 40000h (256K) and
               9FFFFh (640K).  However, the range can extend below and
               above this limit if the hardware and memory manager have the
               capability.

               An operating system won't have to invoke Function 27 to
               obtain this handle because it can assume the handle already
               exists and is available for use immediately after the
               expanded memory device driver installs.  When an operating
               system wants to use this handle, it uses the special handle
               value of 0000h.  The operating system will be able to invoke
               any EMM function using this special handle value.  To
               allocate pages to this handle, the operating system need
               only invoke Function 18 (Reallocate Pages).

               There are two special cases for this handle:

               1.  Function 27 (Allocate Raw Pages subfunction).  This
                   function must never return zero as a handle value.
                   Applications must always invoke Function 27 to allocate
                   pages and obtain a handle which identifies the pages
                   which belong to it.  Since Function 27 never returns a
                   handle value of zero, an application will never gain
                   access to this special handle.

               2.  Function 6 (Deallocate Pages).  If the operating system
                   uses it to deallocate the pages which are allocated to
                   this handle, the pages the handle owns will be returned
                   to the manager for use.  But the handle will not be
                   available for reassignment.  The manager should treat a
                   deallocate pages function request for this handle the
                   same as a reallocate pages function request, where the
                   number of pages to reallocate to this handle is zero.





          EMM Functions                                                 148





          Function 27. Allocate Standard/Raw Pages
          Allocate Raw Pages subfunction



          CALLING PARAMETERS

               AX = 5A01h
                   Contains the Allocate Raw Pages subfunction.

               BX = num_of_raw_pages_to_alloc
                   Contains the number of raw pages the operating system
                   wishes to allocate.


          RESULTS

               These results are valid only if the status returned is zero.

               DX = raw handle
                   Contains a unique EMM raw handle.  The operating system
                   must use this EMM raw handle as a parameter in any
                   function that requires it.  Up to 255 handles may be
                   obtained.  (Both Function 4 and Function 27 must share
                   the same 255 handles).

                   For all functions using this raw handle, the length of
                   the physical and logical pages allocated to it may be
                   non-standard (that is, not 16K bytes).


          REGISTERS MODIFIED

               AX, DX


          STATUS

               AH = 0   SUCCESSFUL.
                   The manager has allocated the raw pages to an assigned
                   EMM raw handle.

               AH = 80h   NON-RECOVERABLE.
                   The manager detected a malfunction in the memory manager
                   software.

               AH = 81h   NON-RECOVERABLE.
                   The manager detected a malfunction in the expanded
                   memory hardware.




          EMM Functions                                                 149





          Function 27. Allocate Standard/Raw Pages
          Allocate Raw Pages subfunction



               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the memory manager is not
                   defined.

               AH = 85h   RECOVERABLE.
                   All EMM handles are being used.

               AH = 87h   RECOVERABLE.
                   There aren't enough expanded memory raw pages present in
                   the system to satisfy the operating system's request.

               AH = 88h   RECOVERABLE.
                   There aren't enough unallocated raw pages to satisfy the
                   operating system's request.

               AH = 8Fh   NON-RECOVERABLE.
                   The subfunction parameter is invalid.


          EXAMPLE

          num_of_raw_pages_to_alloc           DW ?
          emm_raw_handle                      DW ?

          MOV   BX,num_of_raw_pages_to_alloc
          MOV   AX,5A01h                      ; load function code
          INT   67h                           ; call the memory manager
          OR    AH,AH                         ; check EMM status
          JNZ   emm_err_handler               ; jump to error handler
                                              ; on error
          MOV   emm_raw_handle,DX             ; save raw handle

















          EMM Functions                                                 150





          Function 28. Alternate Map Register Set



          Note............................................................
               This function is for use by operating systems only.  The
               operating system can disable this function at any time.
               Refer to Function 30 for a description of how an operating
               system can enable or disable this function.


          Design Considerations

               The hardware support for the entire set of subfunctions
               described is generally not present on every expanded memory
               board from every vendor of expanded memory board products.
               For some of the subfunctions, software emulation is provid-
               ed.  For other subfunctions, a certain protocol in their use
               must be observed.  The subfunctions for which this is most
               crucial are those which address system DMA capabilities.


          System DMA Capabilities & Expanded Memory Support of DMA

               In a multitasking operating system, when one task is waiting
               for DMA to complete, it is useful to be able to switch to
               another task.  This specification describes a capability
               which may be designed into expanded memory boards to provide
               DMA into memory regions which may be mapped out while the
               DMA is occurring.  For expanded memory boards that do not
               provide this, it is crucial to understand that while DMA is
               in progress into a region of mappable memory, the memory
               mapping context cannot be changed.  That is, all DMA action
               must be complete before any remapping of pages can be done.


          Expanded Memory Support of DMA Register Sets

               Expanded memory boards which have DMA register sets could
               support DMA into a region of mappable memory while the
               memory mapping context is being switched.  It is important
               to realize that these DMA register sets are separate from
               the alternate map register sets.  An example of how an OS/E
               might use DMA register sets follows:

                                      Example 1

               1.  Allocate a DMA register set.

               2.  Get current register set.

               3.  Set the DMA register set.

          EMM Functions                                                 151





          Function 28. Alternate Map Register Set



               4.  Map in the memory desired.

               5.  Get the DMA register set.

               6.  Set the original register set.

               7.  Assign the desired DMA channel to the DMA register set.

               The preceding set of calls makes all DMA accesses for the
               desired DMA channel get mapped through the current DMA
               register set regardless of the current register set.  In
               other words, the DMA register set overrides the current
               mapping register set for DMA operations on the DMA channel
               specified.  A DMA channel that is not assigned to a DMA
               register set has all its DMA operations mapped through the
               current mapping register set.

































          EMM Functions                                                 152





          Function 28. Alternate Map Register Set
          Get Alternate Map Register Set subfunction



          Note............................................................
               This function is for use by operating systems only.  The
               operating system can disable this function at any time.
               Refer to Function 30 for a description of how an operating
               system can enable or disable this function.


          PURPOSE

               The subfunction does one of two things depending on the map
               register set which is active at the time this function is
               invoked:

               1.  If the preceding Set Alternate Map Register Set call was
                   done with the alternate map register set equal to zero
                   (BL = 0), these points apply:

                   a.  The context save area pointer saved within EMM by
                       the Set Alternate Map Register subfunction is
                       returned by this call.  This pointer is always
                       returned for boards which do not supply alternate
                       mapping register sets.

                   b.  If the context save area pointer returned is not
                       equal to zero, this subfunction copies the contents
                       of the mapping registers on each expanded memory
                       board in the system into the save area specified by
                       the pointer.  The format of this save area is the
                       same as that returned by Function 15 (Get Page Map
                       subfunction).  This is intended to simulate getting
                       an alternate map register set.  Note that the memory
                       manager does not allocate the space for the context:
                       the operating system must do so.

                   c.  If the context save area pointer returned is equal
                       to zero, this subfunction does not copy the contents
                       of the mapping registers on each expanded memory
                       board in the system into the save area specified by
                       the pointer.

                   d.  The context save area pointer must have been
                       initialized by a previous Set Alternate Map Register
                       Set call.  Note that the value of the context save
                       area pointer saved within EMM is zero immediately
                       after installation.



          EMM Functions                                                 153





          Function 28. Alternate Map Register Set
          Get Alternate Map Register Set subfunction



                   e.  The context save area must be initialized by a
                       previous Get Page Map call (Function 15).

               2.  If the preceding Set Alternate Map Register Set call was
                   done with the alternate map register set greater than
                   zero (BL > 0), then the number of the alternate map
                   register set which is in use at the time that this
                   function is invoked is returned.  The context save area
                   pointer is not returned in this case.


          CALLING PARAMETERS

               AX = 5B00h
                   Contains the Get Alternate Map Register Set subfunction.


          RESULTS

               These results are valid only if the status returned is zero.

               If BL <> 0, current active alternate map register set number
                   Contains the alternate map register set which was active
                   at the time that this function was invoked.

               ES:DI   Unaffected.

               If BL = 0
                   Indicates that a pointer to an area which contains the
                   state of all the map registers on all boards in the
                   system, and any additional information necessary to
                   restore the boards to their original state, has been
                   returned.

               ES:DI = pointer to a map register context save area
                   Contains a pointer to an operating system supplied
                   context save area.  The pointer is in standard seg-
                   ment:offset format.  This pointer is always returned if
                   the expanded memory hardware does not supply alternate
                   mapping register sets.








          EMM Functions                                                 154





          Function 28. Alternate Map Register Set
          Get Alternate Map Register Set subfunction



                   The operating system first passes this pointer to the
                   memory manager whenever it invokes a Set Alternate Map
                   Register Set subfunction (the description follows).  If
                   the OS/E invokes this function before invoking a Set
                   Alternate Map Register Set subfunction, this function
                   returns a pointer value of zero.  The OS/E must have
                   allocated the space for the save area.  However, the OS
                   must request that the memory manager initialize the
                   contents of this save area before it contains any useful
                   information.

                   The OS/E must initialize the save area it has allocated
                   by invoking Function 15 (Get Page Map subfunction).
                   After the OS/E has done this, the save area will contain
                   the state of all the map registers on all boards in the
                   system.  The save area will also contain any additional
                   information necessary to restore the boards to their
                   original state when the operating system invokes a Set
                   Alternate Map Register Set subfunction.


          REGISTERS MODIFIED

               AX, BX, ES:DI


          STATUS

               AH = 0   SUCCESSFUL.
                   The manager got the alternate map register set.

               AH = 80h   NON-RECOVERABLE.
                   The manager detected a malfunction in the memory manager
                   software.

               AH = 81h   NON-RECOVERABLE.
                   The manager detected a malfunction in the expanded
                   memory hardware.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the memory manager is not
                   defined.

               AH = 8Fh   NON-RECOVERABLE.
                   The subfunction parameter is invalid.



          EMM Functions                                                 155





          Function 28. Alternate Map Register Set
          Get Alternate Map Register Set subfunction



               AH = A4h   NON-RECOVERABLE.
                   The operating system denied access to this function.
                   The function cannot be used at this time.


          EXAMPLE

          alt_map_reg_set                        DB ?
          context_save_area_ptr_seg              DW ?
          context_save_area_ptr_offset           DW ?

          MOV   AX,5B00h                         ; load function code
          INT   67h                              ; call the memory manager
          OR    AH,AH                            ; check EMM status
          JNZ   emm_err_handler                  ; jump to error handler
                                                 ; on error
          MOV   alt_map_reg_set,BL
          TEST  BL,BL
          JNZ   no_ptr_returned

          MOV   context_save_area_ptr_seg,ES     ; save pointer values
          MOV   context_save_area_ptr_offset,DI

          no_ptr_returned:
























          EMM Functions                                                 156





          Function 28. Alternate Map Register Set
          Set Alternate Map Register Set subfunction



          Note............................................................
               This function is for use by operating systems only.  The
               operating system can disable this function at any time.
               Refer to Function 30 for a description of how an operating
               system can enable or disable this function.


          PURPOSE

               The subfunction does one of two things, depending on the map
               register set specified:

               1.  If the alternate map register set specified is zero, map
                   register set zero is activated.  If the map register
                   context restore area pointer is not equal to zero, the
                   contents of the restore area pointed to by ES:DI are
                   copied into register set zero on each expanded memory
                   board in the system.  If the pointer is equal to zero,
                   the contents are not copied.

                   Regardless of its value, the map register context
                   restore area pointer is saved within the memory manager.
                   It will be used during the Get Alternate Map Register
                   Set subfunction.

                   The operating system must supply the pointer to the
                   area.  This subfunction is intended to simulate setting
                   an alternate map register set.  Note that the operating
                   system must allocate the space for the context.  The
                   memory manager saves the context save area pointer
                   internally.

               2.  If the alternate map register set specified is not zero,
                   the alternate map register set specified is activated.
                   The restore area, which the operating system is pointing
                   to, is not used.


          CALLING PARAMETERS

               AX = 5B01h
                   Contains the Set Alternate Map Register Set subfunction.






          EMM Functions                                                 157





          Function 28. Alternate Map Register Set
          Set Alternate Map Register Set subfunction



               BL = new alternate map register set number
                   Contains the number of the alternate map register set
                   which is to be activated.

                   If BL <> 0
                       A pointer to a map register context restore area is
                       not required and the contents of ES:DI is unaffected
                       and ignored.  The alternate map register set
                       specified in BL is activated if the board supports
                       it.

                   If BL = 0
                       A pointer to an area which contains the state of all
                       the map registers on all boards in the system, and
                       any additional information necessary to restore the
                       boards to their original state, has been passed in
                       ES:DI.

               ES:DI = pointer to a map register context restore area
                   Contains a pointer to an OS/E supplied map register
                   context restore area.  The pointer is in standard
                   segment:offset format.  This pointer must always be
                   passed if the expanded memory hardware does not supply
                   alternate mapping register sets.

                   The memory manager must save this pointer whenever the
                   OS/E invokes this function.  The OS/E must have allo-
                   cated the space for the restore area.  Additionally, the
                   contents of this restore area must have been initialized
                   by the memory manager before it will contain any useful
                   information.  The OS/E initializes the restore area it
                   has allocated by invoking Function 15 (Get Page Map
                   subfunction).  After the OS/E has done this, the restore
                   area will contain the state of the map registers on all
                   boards in the system, and any additional information
                   necessary to restore the boards to their original state
                   when the operating system invokes a Set Alternate Map
                   Register Set subfunction.


          REGISTERS MODIFIED

               AX





          EMM Functions                                                 158





          Function 28. Alternate Map Register Set
          Set Alternate Map Register Set subfunction



          STATUS

               AH = 0   SUCCESSFUL.
                   The manager set the alternate map register set.

               AH = 80h   NON-RECOVERABLE.
                   The manager detected a malfunction in the memory manager
                   software.

               AH = 81h   NON-RECOVERABLE.
                   The manager detected a malfunction in the expanded
                   memory hardware.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the memory manager is not
                   defined.

               AH = 8Fh   NON-RECOVERABLE.
                   The subfunction parameter is invalid.

               AH = 9Ah   NON-RECOVERABLE.
                   Alternate map register sets are supported, but the
                   alternate map register set specified is not supported.

               AH = 9Ch   NON-RECOVERABLE.
                   Alternate map register sets are not supported, and the
                   alternate map register set specified is not zero.

               AH = 9Dh   NON-RECOVERABLE.
                   Alternate map register sets are supported, but the
                   alternate map register set specified is either not
                   defined or not allocated.

               AH = A3h   NON-RECOVERABLE.
                   The contents of the source array have been corrupted, or
                   the pointer passed to the subfunction is invalid.

               AH = A4h   NON-RECOVERABLE.
                   The operating system has denied access to this function.
                   The function cannot be used at this time.








          EMM Functions                                                 159





          Function 28. Alternate Map Register Set
          Set Alternate Map Register Set subfunction



          EXAMPLE

          alt_map_reg_set                        DB ?
          context_restore_area_ptr_seg           DW ?
          context_restore_area_ptr_offset        DW ?

          MOV   AX,5B01h                         ; load function code
          MOV   BL,alt_map_reg_set
          TEST  BL,BL
          JZ    no_ptr_passed

          MOV   ES,context_restore_area_ptr_seg
          MOV   DI,context_restore_area_ptr_offset

          no_ptr_passed:

          INT   67h                              ; call the memory manger
          OR    AH,AH                            ; check EMM status
          JNZ   emm_err_handler                  ; jump to error handler
                                                 ; on error




























          EMM Functions                                                 160





          Function 28. Alternate Map Register Set
          Get Alternate Map Save Array Size subfunction



          Note............................................................
               This function is for use by operating systems only.  The
               operating system can disable this function at any time.
               Refer to Function 30 for a description of how an operating
               system can enable or disable this function.


          PURPOSE

               This subfunction returns the storage requirements for the
               map register context save area referenced by the other
               subfunctions.


          CALLING PARAMETERS

               AX = 5B02h
                   Contains the Get Alternate Map Save Array Size subfunc-
                   tion.


          RESULTS

               These results are valid only if the status returned is zero.

               DX = size_of_array
                   Contains the number of bytes that will be transferred to
                   the memory area supplied by an operating system whenever
                   an operating system requests the Get, Set, or Get and
                   Set subfunction.


          REGISTERS MODIFIED

               AX, DX


          STATUS

               AH = 0   SUCCESSFUL.
                   The manager has returned the array size.

               AH = 80h   NON-RECOVERABLE.
                   The manager detected a malfunction in the memory manager
                   software.



          EMM Functions                                                 161





          Function 28. Alternate Map Register Set
          Get Alternate Map Save Array Size subfunction



               AH = 81h   NON-RECOVERABLE.
                   The manager detected a malfunction in the expanded
                   memory hardware.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the memory manager is not
                   defined.

               AH = 8Fh   NON-RECOVERABLE.
                   The subfunction parameter is invalid.

               AH = A4h   NON-RECOVERABLE.
                   The operating system has denied access to this function.
                   The function cannot be used at this time.


          EXAMPLE

          size_of_array                  DW ?

          MOV   AX,5B02h                 ; load function code
          INT   67h                      ; call the memory manager
          OR    AH,AH                    ; check EMM status
          JNZ   emm_err_handler          ; jump to error handler on error
          MOV   size_of_array,DX         ; save size of array























          EMM Functions                                                 162





          Function 28. Alternate Map Register Set
          Allocate Alternate Map Register Set subfunction



          Note............................................................
               This function is for use by operating systems only.  The
               operating system can disable this function at any time.
               Refer to Function 30 for a description of how an operating
               system can enable or disable this function.


          PURPOSE

               The Allocate Alternate Map Register Set subfunction gets the
               number of an alternate map register set for an operating
               system if an alternate map register set is currently
               available for use.  If the hardware does not support
               alternate map register sets, an alternate map register set
               number of zero will be returned.

               The alternate map register set allocated may be referred to
               by this number when using the Get or Set Alternate Map
               Register Set subfunctions.  The operating system can use
               these subfunctions to switch map contexts very rapidly on
               expanded memory boards with alternate map register sets.

               This subfunction copies the currently active alternate map
               register set's contents into the newly allocated alternate
               map register set's mapping registers.  This is done so that
               when the OS/E performs a Set Alternate Map Register Set
               subfunction the memory mapped before the allocation of the
               new alternate map will be available for reading and writing.
               This function does not actually change the alternate map
               register set in use, but in addition to allocating a new
               alternate map register set, it prepares the new alternate
               map register set for a subsequent Set Alternate Map Register
               Set subfunction.


          CALLING PARAMETERS

               AX = 5B03h
                   Contains the Allocate Alternate Map Register Set
                   subfunction.








          EMM Functions                                                 163





          Function 28. Alternate Map Register Set
          Allocate Alternate Map Register Set subfunction



          RESULTS

               These results are valid only if the status returned is zero.

               BL = alternate map register set number
                   Contains the number of an alternate map register set.
                   If there are no alternate map register sets supported by
                   the hardware, a zero will be returned.  In this case,
                   the Get Alternate Map function (Function 28) should be
                   invoked in order to obtain a pointer to a map register
                   context save area.  The OS/E must supply this area.  The
                   save area is necessary because the hardware doesn't
                   support alternate map register sets.


          REGISTERS MODIFIED

               AX, BX


          STATUS

               AH = 0   SUCCESSFUL.
                   The manager has returned the alternate map register set
                   number.

               AH = 80h   NON-RECOVERABLE.
                   The manager detected a malfunction in the memory manager
                   software.

               AH = 81h   NON-RECOVERABLE.
                   The manager detected a malfunction in the expanded
                   memory hardware.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the memory manager is not
                   defined.

               AH = 8Fh   NON-RECOVERABLE.
                   The subfunction parameter is invalid.

               AH = 9Bh   NON-RECOVERABLE.
                   Alternate map register sets are supported.  However, all
                   alternate map register sets are currently allocated.




          EMM Functions                                                 164





          Function 28. Alternate Map Register Set
          Allocate Alternate Map Register Set subfunction



               AH = A4h   NON-RECOVERABLE.
                   The operating system has denied access to this function.
                   The function cannot be used at this time.


          EXAMPLE

          alt_map_reg_num                DB ?

          MOV   AX,5B03h                 ; load function code
          INT   67h                      ; call the memory manager
          OR    AH,AH                    ; check EMM status
          JNZ   emm_err_handler          ; jump to error handler on error
          MOV   alt_map_reg_num,BL       ; save number of
                                         ; alternate map register set

































          EMM Functions                                                 165





          Function 28. Alternate Map Register Set
          Deallocate Alternate Map Register Set subfunction



          Note............................................................
               This function is for use by operating systems only.  The
               operating system can disable this function at any time.
               Refer to Function 30 for a description of how an operating
               system can enable or disable this function.


          PURPOSE

               The Deallocate Alternate Map Register Set subfunction
               returns the alternate map register set to the memory manager
               for future use.  The memory manager may reallocate the
               alternate map register set when needed.

               This subfunction also makes the mapping context of the
               alternate map register specified unavailable for reading or
               writing (unmapping).  This protects the pages previously
               mapped in an alternate map register set by making them
               inaccessible.  Note that the current alternate map register
               set cannot be deallocated.  This makes all memory which was
               currently mapped into conventional and expanded memory
               inaccessible.


          CALLING PARAMETERS

               AX = 5B04h
                   Contains the Deallocate Alternate Map Register Set
                   subfunction.

               BL = alternate register set number
                   Contains the number of the alternate map register set to
                   deallocate.  Map register set zero cannot be allocated
                   or deallocated.  However, if alternate map register set
                   zero is specified and this subfunction is invoked, no
                   error will be returned.  The function invocation is
                   ignored in this case.


          REGISTERS MODIFIED

               AX






          EMM Functions                                                 166





          Function 28. Alternate Map Register Set
          Deallocate Alternate Map Register Set subfunction



          STATUS

               AH = 0   SUCCESSFUL.
                   The manager has deallocated the alternate map register
                   set.

               AH = 80h   NON-RECOVERABLE.
                   The manager detected a malfunction in the memory manager
                   software.

               AH = 81h   NON-RECOVERABLE.
                   The manager detected a malfunction in the expanded
                   memory hardware.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the memory manager is not
                   defined.

               AH = 8Fh   NON-RECOVERABLE.
                   The subfunction parameter is invalid.

               AH = 9Ch   NON-RECOVERABLE.
                   Alternate map register sets are not supported and the
                   alternate map register set specified is not zero.

               AH = 9Dh   NON-RECOVERABLE.
                   Alternate map register sets are supported, but the
                   alternate map register set specified is either not
                   defined or not allocated.

               AH = A4h   NON-RECOVERABLE.
                   The operating system has denied access to this function.
                   The function cannot be used at this time.


          EXAMPLE

          alternate_map_reg_set               DB ?

          MOV   BL,alternate_map_reg_set      ; specify alternate map
                                              ; register set
          MOV   AX,5B04h                      ; load function code
          INT   67h                           ; call the memory manager
          OR    AH,AH                         ; check EMM status
          JNZ   emm_err_handler               ; jump to error handler
                                              ; on error


          EMM Functions                                                 167





          Function 28. Alternate Map Register Set
          Allocate DMA Register Set subfunction



          Note............................................................
               This function is for use by operating systems only.  The
               operating system can disable this function at any time.
               Refer to Function 30 for a description of how an operating
               system can enable or disable this function.


          PURPOSE

               The Allocate DMA Register Set subfunction gets the number of
               a DMA register set for an OS/E, if a DMA register set is
               currently available for use.  If the hardware does not
               support DMA register sets, a DMA register set number of zero
               will be returned.

               In a multitasking operating system, when one task is waiting
               for DMA to complete, it is useful to be able to switch to
               another task.  However, if the DMA is being mapped through
               the current register set, the switching cannot occur.  That
               is, all DMA action must be complete before any remapping of
               pages can be done.

               The operating system would initiate a DMA operation on a
               specific DMA channel using a specific alternate map register
               set.  This alternate map register set would not be used
               again, by the operating system or an application, until
               after the DMA operation is complete.  The operating system
               guarantees this by not changing the contents of the alter-
               nate map register set, or allowing an application to change
               the contents of the alternate map register set, for the
               duration of the DMA operation.


          CALLING PARAMETERS

               AX = 5B05h
                   Contains the Allocate DMA Register Set subfunction.


          RESULTS

               These results are valid only if the status returned is zero.

               BL = DMA register set number
                   Contains the number of a DMA register set.  If there are
                   no DMA register sets supported by the hardware, a zero
                   will be returned.

          EMM Functions                                                 168





          Function 28. Alternate Map Register Set
          Allocate DMA Register Set subfunction



          REGISTERS MODIFIED

               AX, BX


          STATUS

               AH = 0   SUCCESSFUL.
                   The manager has allocated the DMA register set.

               AH = 80h   NON-RECOVERABLE.
                   The manager detected a malfunction in the memory manager
                   software.

               AH = 81h   NON-RECOVERABLE.
                   The manager detected a malfunction in the expanded
                   memory hardware.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the memory manager is not
                   defined.

               AH = 8Fh   NON-RECOVERABLE.
                   The subfunction parameter is invalid.

               AH = 9Bh   NON-RECOVERABLE.
                   DMA register sets are supported.  However, all DMA
                   register sets are currently allocated.

               AH = A4h   NON-RECOVERABLE.
                   Access to this function has been denied by the operating
                   system.  The function cannot be used at this time.


          EXAMPLE

          DMA_reg_set_number                  DB ?

          MOV   AX,5B05h                      ; load function code
          INT   67h                           ; call memory manager
          OR    AH,AH                         ; check EMM status
          JNZ   emm_err_handler               ; jump to error handler
                                              ; on error
          MOV   DMA_reg_set_number,BL         ; save number of DMA
                                              ; register set



          EMM Functions                                                 169





          Function 28. Alternate Map Register Set
          Enable DMA on Alternate Map Register Set subfunction



          Note............................................................
               This function is for use by operating systems only.  The
               operating system can disable this function at any time.
               Refer to Function 30 for a description of how an operating
               system can enable or disable this function.


          PURPOSE

               This subfunction allows DMA accesses on a specific DMA
               channel to be associated with a specific alternate map
               register set.  In a multitasking operating system, when a
               task is waiting for the completion of DMA, it is useful to
               be able to switch to another task until the DMA operation
               completes.

               Any DMA on the specified channel will go through the speci-
               fied DMA register set regardless of the current register
               set.  If a DMA channel is not assigned to a DMA register
               set, DMA for that channel will be mapped through the current
               register set.


          CALLING PARAMETERS

               AX = 5B06h
                   Contains the Enable DMA on Alternate Map Register Set
                   subfunction.

               BL = DMA register set number
                   Contains the number of the alternate map register set to
                   be used for DMA operations on the DMA channel specified
                   by DL.  If the alternate map register set specified is
                   zero, no special action will be taken on DMA accesses
                   for the DMA channel specified.

               DL = DMA channel number
                   Contains the DMA channel which is to be associated with
                   the DMA map register set specified in BL.


          REGISTERS MODIFIED

               AX




          EMM Functions                                                 170





          Function 28. Alternate Map Register Set
          Enable DMA on Alternate Map Register Set subfunction



          STATUS

               AH = 0   SUCCESSFUL.
                   The manager has enabled DMA on the DMA register set and
                   the DMA channel specified.

               AH = 80h   NON-RECOVERABLE.
                   The manager detected a malfunction in the memory manager
                   software.

               AH = 81h   NON-RECOVERABLE.
                   The manager detected a malfunction in the expanded
                   memory hardware.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the memory manager is not
                   defined.

               AH = 8Fh   NON-RECOVERABLE.
                   The subfunction parameter is invalid.

               AH = 9Ah   NON-RECOVERABLE.
                   Alternate DMA register sets are supported, but the
                   alternate DMA register set specified is not supported.

               AH = 9Ch   NON-RECOVERABLE.
                   Alternate DMA register sets are not supported, and the
                   DMA register set specified is not zero.

               AH = 9Dh   NON-RECOVERABLE.
                   DMA register sets are supported, but the DMA register
                   set specified is either not defined or not allocated.

               AH = 9Eh   NON-RECOVERABLE.
                   Dedicated DMA channels are not supported.

               AH = 9Fh   NON-RECOVERABLE.
                   Dedicated DMA channels are supported, but the DMA
                   channel specified is not supported.

               AH = A4h   NON-RECOVERABLE.
                   The operating system has denied access to this function.
                   The function cannot be used at this time.





          EMM Functions                                                 171





          Function 28. Alternate Map Register Set
          Enable DMA on Alternate Map Register Set subfunction



          EXAMPLE

          alt_map_reg_set                DB ?
          DMA_channel_num                DB ?

          MOV   BL,alt_map_reg_set
          MOV   DL,DMA_channel_num
          MOV   AX,5B06h                 ; load function code
          INT   67h                      ; call the memory manager
          OR    AH,AH                    ; check EMM status
          JNZ   emm_err_handler          ; jump to error handler on error





































          EMM Functions                                                 172





          Function 28. Alternate Map Register Set
          Disable DMA on Alternate Map Register Set subfunction



          Note............................................................
               This function is for use by operating systems only.  The
               operating system can disable this function at any time.
               Refer to Function 30 for a description of how an operating
               system can enable or disable this function.


          PURPOSE

               This subfunction disables DMA accesses for all DMA channels
               which were associated with a specific alternate map register
               set.


          CALLING PARAMETERS

               AX = 5B07h
                   Contains the Disable DMA on Alternate Map Register Set
                   subfunction.

               BL = alternate register set number
                   Contains the number of the DMA register set for which
                   all operations are to be disabled.  If the alternate map
                   register set specified is zero, no action will be taken.


          REGISTERS MODIFIED

               AX


          STATUS

               AH = 0   SUCCESSFUL.
                   The manager has disabled DMA operations on the alternate
                   DMA register set.

               AH = 80h   NON-RECOVERABLE.
                   The manager detected a malfunction in the memory manager
                   software.

               AH = 81h   NON-RECOVERABLE.
                   The manager detected a malfunction in the expanded
                   memory hardware.




          EMM Functions                                                 173





          Function 28. Alternate Map Register Set
          Disable DMA on Alternate Map Register Set subfunction



               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the memory manager is not
                   defined.

               AH = 8Fh   NON-RECOVERABLE.
                   The subfunction parameter is invalid.

               AH = 9Ah   NON-RECOVERABLE.
                   Alternate DMA register sets are supported, but the
                   alternate DMA register set specified is not supported.

               AH = 9Ch   NON-RECOVERABLE.
                   Alternate DMA register sets are not supported, and the
                   DMA register set specified is not zero.

               AH = 9Dh   NON-RECOVERABLE.
                   DMA register sets are supported, but the DMA register
                   set specified is either not defined or not allocated.

               AH = 9Eh   NON-RECOVERABLE.
                   Dedicated DMA channels are not supported.

               AH = 9Fh   NON-RECOVERABLE.
                   Dedicated DMA channels are supported, but the DMA
                   channel specified is not supported.

               AH = A4h   NON-RECOVERABLE.
                   The operating system has denied access to this function.
                   The function cannot be used at this time.


          EXAMPLE

          DMA_reg_set                    DB ?

          MOV   BL,DMA_reg_set
          MOV   AX,5B07h                 ; load function code
          INT   67h                      ; call the memory manager
          OR    AH,AH                    ; check EMM status
          JNZ   emm_err_handler          ; jump to error handler on error








          EMM Functions                                                 174





          Function 28. Alternate Map Register Set
          Deallocate DMA Register Set subfunction



          Note............................................................
               This function is for use by operating systems only.  The
               operating system can disable this function at any time.
               Refer to Function 30 for a description of how an operating
               system can enable or disable this function.


          PURPOSE

               The Deallocate DMA Register Set subfunction deallocates the
               specified DMA register set.


          CALLING PARAMETERS

               AX = 5B08h
                   Contains the Deallocate DMA Register Set subfunction.

               BL = DMA register set number
                   Contains the number of the DMA register set which should
                   not be used for DMA operations any longer.  The DMA
                   register set would have been previously allocated and
                   enabled for DMA operations on a specific DMA channel.
                   If the DMA register set specified is zero, no action
                   will be taken.


          REGISTERS MODIFIED

               AX


          STATUS

               AH = 0   SUCCESSFUL.
                   The manager has deallocated the DMA register set.

               AH = 80h   NON-RECOVERABLE.
                   The manager detected a malfunction in the memory manager
                   software.

               AH = 81h   NON-RECOVERABLE.
                   The manager detected a malfunction in the expanded
                   memory hardware.




          EMM Functions                                                 175





          Function 28. Alternate Map Register Set
          Deallocate DMA on Alternate Map Register Set subfunction



               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the memory manager is not
                   defined.

               AH = 8Fh   NON-RECOVERABLE.
                   The subfunction parameter is invalid.

               AH = 9Ch   NON-RECOVERABLE.
                   DMA register sets are not supported, and the DMA
                   register set specified is not zero.

               AH = 9Dh   NON-RECOVERABLE.
                   DMA register sets are supported, but the DMA register
                   set specified is either not defined or not allocated.

               AH = A4h   NON-RECOVERABLE.
                   The operating system has denied access to this function.
                   The function cannot be used at this time.


          EXAMPLE

          DMA_reg_set_num                DB ?

          MOV   BL,DMA_reg_set_num
          MOV   AX,5B08h                 ; load function code
          INT   67h                      ; call the memory manager
          OR    AH,AH                    ; check EMM status
          JNZ   emm_err_handler          ; jump to error handler on error



















          EMM Functions                                                 176





          Function 29. Prepare Expanded Memory Hardware For Warm Boot



          PURPOSE

               This function prepares the expanded memory hardware for an
               impending warm boot.  This function assumes that the next
               operation that the operating system performs is a warm boot
               of the system.  In general, this function will effect the
               current mapping context, the alternate register set in use,
               and any other expanded memory hardware dependencies which
               need to be initialized at boot time.  If an application
               decides to map memory below 640K, the application must trap
               all possible conditions leading to a warm boot and invoke
               this function before performing the warm boot itself.


          CALLING PARAMETERS

               AH = 5Ch
                   Contains the Prepare Expanded Memory Hardware for Warm
                   Boot function.


          REGISTERS MODIFIED

               AX


          STATUS

               AH = 0   SUCCESSFUL.
                   The manager has prepared the expanded memory hardware
                   for a warm boot.

               AH = 80h   NON-RECOVERABLE.
                   The manager detected a malfunction in the memory manager
                   software.

               AH = 81h   NON-RECOVERABLE.
                   The manager detected a malfunction in the expanded
                   memory hardware.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the memory manager is not
                   defined.






          EMM Functions                                                 177





          Function 29. Prepare Expanded Memory Hardware for Warm Boot



          EXAMPLE

          MOV   AH,5Ch                   ; load function code
          INT   67h                      ; call the memory manager
          OR    AH,AH                    ; check EMM status
          JNZ   emm_err_handler          ; jump to error handler on error











































          EMM Functions                                                 178





          Function 30. Enable/Disable OS/E Function Set Functions
          Enable OS/E Function Set subfunction



          Note............................................................
               This function is for use by operating systems only.  The
               operating system can disable this function at any time.


          PURPOSE

               This subfunction provides an OS/E with the ability to enable
               all programs or device drivers to use the OS/E specific
               functions.  The capability is provided only for an OS/E
               which manages regions of mappable conventional memory and
               cannot permit programs to use any of the functions which
               affect mappable conventional memory regions, but must be
               able to use these functions itself.  When an OS/E disables
               these functions and a program attempts to use them, the
               memory manager returns a status to the program indicating
               that the OS/E has denied the program access to the function.
               In other words, the functions will not work when disabled.
               However, all programs may use them when enabled.

               The OS/E (Operating System/Environment) functions this
               subfunction enables are:

               Function 26.  Get Expanded Memory Hardware Information.
               Function 28.  Alternate Map Register Sets.
               Function 30.  Enable/Disable Operating System Functions.

               It appears contradictory that the OS/E can re-enable these
               functions when the function which re-enables them is itself
               disabled.  An overview of the process follows.

               The memory manager enables all the OS/E specific functions,
               including this one, when it is loaded.  The OS/E gets
               exclusive access to these functions by invoking either of
               the Enable/Disable OS/E Function Set subfunctions before any
               other software does.

               On the first invocation of either of these subfunctions, the
               memory manager returns an access_key which the OS/E must use
               in all future invocations of either of these subfunctions.
               The memory manager does not require the access_key on the
               first invocation of the Enable/Disable OS/E Function Set
               subfunctions.





          EMM Functions                                                 179





          Function 30. Enable/Disable OS/E Function Set Functions
          Enable OS/E Function Set subfunction



               On all subsequent invocations, the access_key is required
               for either the Enable or Disable OS/E Function Set subfunc-
               tions.  Since the access_key is returned only on the first
               invocation of the Enable/Disable OS/E Function Set subfunc-
               tions, and presumably the OS/E is the first software to
               invoke this function, only the OS/E obtains a copy of this
               key.  The memory manager must return an access key with a
               random value, a fixed value key defeats the purpose of
               providing this level of security for an OS/E.


          CALLING PARAMETERS

               AX = 5D00h
                   Contains the Enable OS/E Function Set subfunction.

               BX,CX = access_key
                   Required on all function invocations after the first.
                   The access_key value returned by the first function
                   invocation is required.


          RESULTS

               These results are valid only if the status returned is zero.

               BX,CX = access_key
                   Returned only on the first function invocation, the
                   memory manager returns a random valued key which will be
                   required thereafter for the execution of this function.
                   On all invocations after the first, this key is not
                   returned.  Neither BX nor CX is affected after the first
                   time this function is invoked.


          REGISTERS MODIFIED

               AX, BX, CX


          STATUS

               AH = 0   SUCCESSFUL.
                   The operating system function set has been enabled.




          EMM Functions                                                 180





          Function 30. Enable/Disable OS/E Function Set Functions
          Enable OS/E Function Set subfunction



               AH = 80h   NON-RECOVERABLE.
                   The manager detected a malfunction in the memory manager
                   software.

               AH = 81h   NON-RECOVERABLE.
                   The manager detected a malfunction in the expanded
                   memory hardware.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the memory manager is not
                   defined.

               AH = 8Fh   NON-RECOVERABLE.
                   The subfunction parameter is invalid.

               AH = A4h   NON-RECOVERABLE.
                   The operating system has denied access to this function.
                   The function cannot be used at this time.  The value of
                   the key which was passed to this function does not
                   entitle the program to execute this function.


          EXAMPLE

          First invocation

          access_key                     DW 2 DUP (?)

          MOV   AX,5D00h                 ; load function code
          INT   67h                      ; call the memory manager
          OR    AH,AH                    ; check EMM status
          JNZ   emm_err_handler          ; jump to error handler on error
          MOV   access_key[0],BX
          MOV   access_key[2],CX


          All invocations after the first

          access_key                     DW 2 DUP (?)

          MOV   BX,access_key[0]
          MOV   CX,access_key[2]
          MOV   AX,5D00h                 ; load function code
          INT   67h                      ; call the memory manager
          OR    AH,AH                    ; check EMM status
          JNZ   emm_err_handler          ; jump to error handler on error


          EMM Functions                                                 181





          Function 30. Enable/Disable OS/E Function Set Functions
          Disable OS/E Function Set subfunction



          Note............................................................
               This function is for use by operating systems only.  The
               operating system can disable this function at any time.


          PURPOSE

               This subfunction provides an OS/E with the ability to
               disable all programs or device drivers from using the OS/E
               specific functions.  The capability is provided only for an
               OS/E which manages regions of mappable conventional memory
               and cannot permit programs to use any of the functions which
               would affect mappable conventional memory regions.  When an
               OS/E disables these functions and a program attempts to use
               them, the memory manager returns a status to the program
               indicating that the OS/E has denied the program access to
               the function.  In other words, the functions will not work
               when disabled.

               The OS/E (Operating System) functions which are disabled by
               this subfunction are:

               Function 26.  Get Expanded Memory Hardware Information.
               Function 28.  Alternate Map Register Sets.
               Function 30.  Enable/Disable Operating System Functions.


          CALLING PARAMETERS

               AX = 5D01h
                   Contains the Disable OS/E Function Set subfunction.

               BX,CX = access_key
                   Required on all function invocations after the first.
                   The access_key value returned by the first function
                   invocation is required.












          EMM Functions                                                 182





          Function 30. Enable/Disable OS/E Function Set Functions
          Disable OS/E Function Set subfunction



          RESULTS

               These results are valid only if the status returned is zero.

               BX,CX = access_key
                   Returned only on the first function invocation, the
                   memory manager returns a random valued key which will be
                   required thereafter for the execution of this function.
                   On all invocations after the first, this key is not
                   returned.  Neither BX nor CX is affected after the first
                   time this function is invoked.


          REGISTERS MODIFIED

               AX, BX, CX


          STATUS

               AH = 0   SUCCESSFUL.
                   The operating system function set has been disabled.

               AH = 80h   NON-RECOVERABLE.
                   The manager detected a malfunction in the memory manager
                   software.

               AH = 81h   NON-RECOVERABLE.
                   The manager detected a malfunction in the expanded
                   memory hardware.

               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the memory manager is not
                   defined.

               AH = 8Fh   NON-RECOVERABLE.
                   The subfunction parameter is invalid.

               AH = A4h   NON-RECOVERABLE.
                   The operating system has denied access to this function.
                   The function cannot be used at this time.  The value of
                   the key which was passed to this function does not
                   entitle the program to execute this function.





          EMM Functions                                                 183





          Function 30. Enable/Disable OS/E Function Set Functions
          Disable OS/E Function Set subfunction



          EXAMPLE

          First Function invocation

          access_key                     DW 2 DUP (?)

          MOV   AX,5D01h                 ; load function code
          INT   67h                      ; call the memory manager
          OR    AH,AH                    ; check EMM status
          JNZ   emm_err_handler          ; jump to error handler on error
          MOV   access_key[0],BX
          MOV   access_key[2],CX


          All invocations after the first

          access_key                     DW 2 DUP (?)

          MOV   BX,access_key[0]
          MOV   CX,access_key[2]
          MOV   AX,5D01h                 ; load function code
          INT   67h                      ; call the memory manager
          OR    AH,AH                    ; check EMM status
          JNZ   emm_err_handler          ; jump to error handler on error
























          EMM Functions                                                 184





          Function 30. Enable/Disable OS/E Function Set Functions
          Return Access Key subfunction



          Note............................................................
               This function is for use by operating systems only.  The
               operating system can disable this function at any time.


          PURPOSE

               This subfunction provides an OS/E with the ability to return
               the access key to the memory manager.  Returning the access
               key to the memory manager places the memory manager in the
               state it is in at installation time (regarding the use of
               the OS/E function set and the access key).  That is, access
               to the OS/E function set is enabled.  Upon execution of the
               next enable/disable OS/E function set subfunction, the
               access key will once again be returned.


          CALLING PARAMETERS

               AX = 5D02h
                   Contains the Return Access Key subfunction.

               BX,CX = access_key
                   Required on all function invocations.  The access_key
                   value returned by the first function invocation of the
                   enable or disable subfunctions is required.


          REGISTERS MODIFIED

               AX


          STATUS

               AH = 0   SUCCESSFUL.
                   The access key has been returned to the memory manager.

               AH = 80h   NON-RECOVERABLE.
                   The manager detected a malfunction in the memory manager
                   software.

               AH = 81h   NON-RECOVERABLE.
                   The manager detected a malfunction in the expanded
                   memory hardware.



          EMM Functions                                                 185





          Function 30. Enable/Disable OS/E Function Set Functions
          Return Access Key subfunction



               AH = 84h   NON-RECOVERABLE.
                   The function code passed to the memory manager is not
                   defined.

               AH = 8Fh   NON-RECOVERABLE.
                   The subfunction parameter is invalid.

               AH = A4h   NON-RECOVERABLE.
                   The operating system has denied access to this function.
                   The function cannot be used at this time.  The value of
                   the key which was passed to this function does not
                   entitle the program to execute this function.


          EXAMPLE

          access_key                     DW 2 DUP (?)

          MOV   BX,access_key[0]
          MOV   CX,access_key[2]
          MOV   AX,5D02h                 ; load function code
          INT   67h                      ; call the memory manager
          OR    AH,AH                    ; check EMM status
          JNZ   emm_err_handler          ; jump to error handler on error
























          EMM Functions                                                 186





          Appendix A
          FUNCTION AND STATUS CODE CROSS REFERENCE TABLES



               This appendix contains two cross reference tables:  one
               lists the function codes and the status codes they return;
               the other lists the status codes and the functions that
               return them.


          Table A-1.  Function and Status Code Cross Reference
          ----------------------------------------------------------------

          Function        Status                 Description

          ----------------------------------------------------------------

             40h    00h, 80h, 81h, 84h   Get Memory Manager Status

             41h    00h, 80h, 81h, 84h   Get Page Frame Segment Address

             42h    00h, 80h, 81h, 84h   Get Unallocated Page Count

             43h    00h, 80h, 81h, 84h   Allocate Pages
                    85h, 87h, 88h, 89h

             44h    00h, 80h, 81h, 83h   Map/Unmap Handle Page
                    84h, 8Ah, 8Bh

             45h    00h, 80h, 81h, 83h   Deallocate Pages
                    84h, 86h

             46h    00h, 80h, 81h, 84h   Get EMM Version

             47h    00h, 80h, 81h, 83h   Save Page Map
                    84h, 8Ch, 8Dh

             48h    00h, 80h, 81h, 83h   Restore Page Map
                    84h, 8Eh

             49h                         Reserved

             4Ah                         Reserved

             4Bh    00h, 80h, 81h, 84h   Get EMM Handle Count

             4Ch    00h, 80h, 81h, 83h   Get EMM Handle Pages
                    84h

             4Dh    00h, 80h, 81h, 84h   Get All EMM Handle Pages


          Cross Reference Tables                                        187





          Table A-1.  Function and Status Code Cross Reference (continued)
          ----------------------------------------------------------------

          Function        Status                 Description

          ----------------------------------------------------------------

           4E00h    00h, 80h, 81h, 84h   Get Page Map
                    8Fh

           4E01h    00h, 80h, 81h, 84h   Set Page Map
                    8Fh, A3h

           4E02h    00h, 80h, 81h, 84h   Get & Set Page Map
                    8Fh, A3h

           4E03h    00h, 80h, 81h, 84h   Get Size of Page Map Save Array
                    8Fh

           4F00h    00h, 80h, 81h, 84h   Get Partial Page Map
                    8Bh, 8Fh, A3h

           4F01h    00h, 80h, 81h, 84h   Set Partial Page Map
                    8Fh, A3h

           4F02h    00h, 80h, 81h, 84h   Get Size of Partial Page Map Array
                    8Bh, 8Fh

           5000h    00h, 80h, 81h, 83h   Map/Unmap Multiple Handle Pages
                    84h, 8Ah, 8Bh, 8Fh   (physical page number mode)

           5001h    00h, 80h, 81h, 83h   Map/Unmap Multiple Handle Pages
                    84h, 8Ah, 8Bh, 8Fh   (segment address mode)

             51h    00h, 80h, 81h, 83h   Reallocate Pages
                    84h, 87h, 88h

           5200h    00h, 80h, 81h, 83h   Get Handle Attribute
                    84h, 8Fh, 91h

           5201h    00h, 80h, 81h, 83h   Set Handle Attribute
                    84h, 8Fh, 90h, 91h

           5202h    00h, 80h, 81h, 84h   Get Handle Attribute Capability
                    8Fh

           5300h    00h, 80h, 81h, 83h   Get Handle Name
                    84h, 8Fh

           5301h    00h, 80h, 81h, 83h   Set Handle Name
                    84h, 8Fh, A1h


          Cross Reference Tables                                        188





          Table A-1.  Function and Status Code Cross Reference (continued)
          ----------------------------------------------------------------

          Function        Status                 Description

          ----------------------------------------------------------------

           5400h    00h, 80h, 81h, 84h   Get Handle Directory
                    8Fh

           5401h    00h, 80h, 81h, 84h   Search for Named Handle
                    8Fh, A0h, A1h

           5402h    00h, 80h, 81h, 84h   Get Total Handles
                    8Fh

           5500h    00h, 80h, 81h, 83h   Alter Page Map & Jump (Physical
                    84h, 8Ah, 8Bh, 8Fh   page mode)

           5501h    00h, 80h, 81h, 83h   Alter Page Map & Jump (Segment
                    84h, 8Ah, 8Bh, 8Fh   address mode)

           5600h    00h, 80h, 81h, 83h   Alter Page Map & Call (Physical
                    84h, 8Ah, 8Bh, 8Fh   page mode)

           5601h    00h, 80h, 81h, 83h   Alter Page Map & Call (Segment
                    84h, 8Ah, 8Bh, 8Fh   address mode)

           5602h    00h, 80h, 81h, 84h   Get Alter Page Map & Call Stack
                    8Fh                  Space Size

           5700h    00h, 80h, 81h, 83h   Move Memory Region
                    84h, 8Ah, 8Fh, 92h
                    93h, 94h, 95h, 96h
                    98h, A2h

           5701h    00h, 80h, 81h, 83h   Exchange Memory Region
                    84h, 8Ah, 8Fh, 93h
                    94h, 95h, 96h, 97h
                    98h, A2h

           5800h    00h, 80h, 81h, 84h   Get Mappable Physical Address
                    8Fh                  Array

           5801h    00h, 80h, 81h, 84h   Get Mappable Physical Address
                    8Fh                  Array Entries

           5900h    00h, 80h, 81h, 84h   Get Expanded Memory Hardware
                    8Fh, A4h             Information

           5901h    00h, 80h, 81h, 84h   Get Unallocated Raw Page Count
                    8Fh

          Cross Reference Tables                                        189





          Table A-1.  Function and Status Code Cross Reference (continued)
          ----------------------------------------------------------------

          Function        Status                 Description

          ----------------------------------------------------------------

           5A00h    00h, 80h, 81h, 84h   Allocate Standard Pages
                    85h, 87h, 88h, 8Fh

           5A01h    00h, 80h, 81h, 84h   Allocate Raw Pages
                    85h, 87h, 88h, 8Fh

           5B00h    00h, 80h, 81h, 84h   Get Alternate Map Register Set
                    8Fh, A4h

           5B01h    00h, 80h, 81h, 84h   Set Alternate Map Register Set
                    8Fh, 9Ah, 9Ch, 9Dh
                    A3h, A4h

           5B02h    00h, 80h, 81h, 84h   Get Alternate Map Save Array Size
                    8Fh, A4h

           5B03h    00h, 80h, 81h, 84h   Allocate Alternate Map Register
                    8Fh, 9Bh, A4h        Set

           5B04h    00h, 80h, 81h, 84h   Deallocate Alternate Map Register
                    8Fh, 9Ch, 9Dh, A4h   Set

           5B05h    00h, 80h, 81h, 84h   Allocate DMA Register Set
                    8Fh, 9Bh, A4h

           5B06h    00h, 80h, 81h, 84h   Enable DMA on Alternate Map
                    8Fh, 9Ah, 9Ch, 9Dh   Register Set
                    9Eh, 9Fh, A4h

           5B07h    00h, 80h, 81h, 84h   Disable DMA on Alternate Map
                    8Fh, 9Ah, 9Ch, 9Dh   Register Set
                    9Eh, 9Fh, A4h

           5B08h    00h, 80h, 81h, 84h   Deallocate DMA Register Set
                    8Fh, 9Ch, 9Dh, A4h

             5Ch    00h, 80h, 81h, 84h   Prepare Expanded Memory Hardware
                                         for Warmboot

           5D00h    00h, 80h, 81h, 84h   Enable Operating System Function
                    8Fh, A4h             Set

           5D01h    00h, 80h, 81h, 84h   Disable Operating System Function
                    8Fh, A4h             Set


          Cross Reference Tables                                        190





          Table A-1.  Function and Status Code Cross Reference (continued)
          ----------------------------------------------------------------

          Function        Status                 Description

          ----------------------------------------------------------------

           5D02h    00h, 80h, 81h, 84h   Return Operating System Access Key
                    8Fh, A4h
          ----------------------------------------------------------------











































          Cross Reference Tables                                        191





          Table A-2.  Status and Function Code Cross Reference
          ----------------------------------------------------------------

          Status      Function                   Description

          ----------------------------------------------------------------

           00h   All                  The function completed normally.

           80h   All                  The memory manager has detected a
                                      malfunction in the expanded memory
                                      software.  A condition has been
                                      detected which would not have
                                      occurred if the memory manager had
                                      been operating correctly.

           81h   All                  The memory manager has detected a
                                      malfunction in the expanded memory
                                      hardware.  A condition has been
                                      detected which would not occur if the
                                      memory hardware were working correct-
                                      ly.  Diagnostics should be run on the
                                      expanded memory system to determine
                                      the source of the problem.

           82h   None                 This error code is not returned in
                                      version 3.2 of the memory manager or
                                      above.  In earlier versions of the
                                      memory manager this code meant a
                                      "busy" status.  This status indicated
                                      that the memory manager was already
                                      processing an expanded memory request
                                      when the current request was made and
                                      is unable to process another request.
                                      In versions 3.2 of the memory manager
                                      and above, the memory manager is
                                      never "busy" and can always honor
                                      requests.

           83h   44h, 45h, 47h, 48h   The memory manager can not find the
                 4Ch, 5000h, 5001h    handle specified.  The program has
                 51h, 5200h, 5201h    probably corrupted its specified
                 5300h, 5301h         handle.  The memory manager does not
                 5500h, 5501h         have any information pertaining to
                 5600h, 5601h         the  specified handle.  The program
                 5700h, 5701h         has probably corrupted its handle.

           84h   All                  The function code passed to the
                                      manager is not currently defined.
                                      Function codes in the range 40h
                                      through 5Dh are currently defined.


          Cross Reference Tables                                        192





          Table A-2.  Status and Function Code Cross Reference (continued)
          ----------------------------------------------------------------

          Status      Function                   Description

          ----------------------------------------------------------------

           85h   43h, 5A00h, 5A01h    No handles are currently available.
                                      All assignable handles are currently
                                      in use.  The program may re-request
                                      the assignment of a handle in the
                                      hope that another program has
                                      released a handle.  The maximum
                                      number of handles that may be
                                      supported is 255.

           86h   45h                  A mapping context restoration error
                                      has been detected.  This error occurs
                                      when a program attempts to return a
                                      handle and there is still a "mapping
                                      context" on the context stack for the
                                      indicated handle.  A program can
                                      recover from this error by restoring
                                      the mapping context before returning
                                      the handle.

           87h   43h, 51h, 5A00h,     The number of total pages that are
                 5A01h                available in the system is insuffi-
                                      cient to honor the request.  The
                                      program can recover from this
                                      condition by requesting fewer pages.

           88h   43h, 51h, 5A00h,     The number of unallocated pages
                 5A01h                currently available is insufficient
                                      to honor the allocation request.  The
                                      program can recover from this
                                      condition by re-posting the request
                                      or by requesting fewer pages.

           89h   43h                  A Function 4 (Allocate Pages) request
                                      has been made specifying zero pages.
                                      Zero pages cannot be assigned to a
                                      handle with Function 4 (Allocate
                                      Pages).  If it is necessary to assign
                                      zero pages to a handle, Function 27
                                      (Allocate Standard Pages and Allocate
                                      Raw Pages subfunctions) may be used.






          Cross Reference Tables                                        193





          Table A-2.  Status and Function Code Cross Reference (continued)
          ----------------------------------------------------------------

          Status      Function                   Description

          ----------------------------------------------------------------

           8Ah   44h, 5000h, 5001h    The logical page to map into memory
                 5500h, 5501h         is out of the range of logical pages
                 5600h, 5601h         which are allocated to the handle.
                 5700h, 5701h         The program can recover from this
                                      condition by attempting to map a
                                      logical page which is within the
                                      bounds for the handle.

           8Bh   44h, 4F00h, 4F02h    One or more of the physical pages is
                 5000h, 5001h         out of the range of allowable
                 5600h, 5601h         physical pages.  Physical page
                 5500h, 5501          numbers are numbered zero-relative.
                                      The program can recover from this
                                      condition by mapping at a physical
                                      page which is in the range from zero
                                      to three.

           8Ch   47h                  The mapping register context save
                                      area is full.  The program can
                                      recover from this condition by
                                      attempting to save the mapping
                                      registers again.

           8Dh   47h                  The mapping register context stack
                                      already has a context associated with
                                      the handle.  The program has at-
                                      tempted to save the mapping register
                                      context when there was already a
                                      context for the handle on the stack.
                                      The program can recover from this
                                      condition by not attempting to save
                                      the context again (this assumes the
                                      mapping register context on the stack
                                      for the handle is correct).












          Cross Reference Tables                                        194





          Table A-2.  Status and Function Code Cross Reference (continued)
          ----------------------------------------------------------------

          Status      Function                   Description

          ----------------------------------------------------------------

           8Eh   48h                  The mapping register context stack
                                      does not have a context associated
                                      with the handle.  The program has
                                      attempted to restore the mapping
                                      register context when there was no
                                      context for the handle on the stack.
                                      The program can recover from this
                                      condition by not attempting to
                                      restore the context again (this
                                      assumes the current mapping register
                                      context is correct).

           8Fh   All functions        The subfunction parameter passed to
                 requiring            the function is not defined.
                 subfunction codes

           90h   5201h                The attribute type is undefined.

           91h   5200h, 5201h         The system configuration does not
                                      support non-volatility.

           92h   5700h                The source and destination expanded
                                      memory regions have the same handle
                                      and overlap.  This is valid for a
                                      move.  The move has been completed
                                      and the destination region has a full
                                      copy of the source region.  However,
                                      at least a portion of the source
                                      region has been overwritten by the
                                      move.  Note that the source and
                                      destination expanded memory regions
                                      with different handles will never
                                      physically overlap because the
                                      different handles specify totally
                                      different regions of expanded memory.











          Cross Reference Tables                                        195





          Table A-2.  Status and Function Code Cross Reference (continued)
          ----------------------------------------------------------------

          Status      Function                   Description

          ----------------------------------------------------------------

           93h   5700h, 5701h         The length of the specified source or
                                      destination expanded memory region
                                      exceeds the length of the expanded
                                      memory region allocated to the
                                      specified source or destination
                                      handle.  There are insufficient pages
                                      allocated to this handle to move/ex-
                                      change a region of the size speci-
                                      fied.  The program can recover from
                                      this condition by attempting to
                                      allocate additional pages to the
                                      destination or source handle or by
                                      reducing the specified length.
                                      However, if the application program
                                      has allocated as much expanded memory
                                      as it thought it needed, this may be
                                      a program error and is therefore not
                                      recoverable.

           94h   5700h, 5701h         The conventional memory region and
                                      expanded memory region overlap.  This
                                      is invalid, the conventional memory
                                      region cannot overlap the expanded
                                      memory region.

           95h   5700h, 5701h         The offset within the logical page
                                      exceeds the length of the logical
                                      page.  The initial source or destina-
                                      tion offsets within an expanded
                                      memory region must be between 0 and
                                      the (length of a logical page - 1) or
                                      16383 (3FFFh).

           96h   5700h, 5701h         Region length exceeds 1M-byte limit.












          Cross Reference Tables                                        196





          Table A-2.  Status and Function Code Cross Reference (continued)
          ----------------------------------------------------------------

          Status      Function                   Description

          ----------------------------------------------------------------

           97h   5701h                The source and destination expanded
                                      memory regions have the SAME handle
                                      AND overlap.  This is invalid; the
                                      source and destination expanded
                                      memory regions cannot have the same
                                      handle and overlap when they are
                                      being exchanged.  Note that the
                                      source and destination expanded
                                      memory regions with different handles
                                      will never physically overlap because
                                      the different handles specify totally
                                      different regions of expanded memory.

           98h   5700h, 5701h         The memory source and destination
                                      types are undefined/not supported.

           9Ah   5B01h, 5B06h         Alternate map register sets are
                 5B07h                supported, but the alternate map
                                      register set specified is not
                                      supported.

           9Bh   5B03h, 5B05h         Alternate map/DMA register sets are
                                      supported.  However, all alternate
                                      map/DMA register sets are currently
                                      allocated.

           9Ch   5B01h, 5B04h         Alternate map/DMA register sets are
                 5B06h, 5B07h         not supported, and the alternate
                 5B08h                map/DMA register set specified is not
                                      zero.

           9Dh   5B01h, 5B04h         Alternate map/DMA register sets are
                 5B06h, 5B07h         supported, but the alternate map
                 5B08h                register set specified is not
                                      defined, not allocated, or is the
                                      currently allocated map register set.

           9Eh   5B06h, 5B07h         Dedicated DMA channels are not
                                      supported.

           9Fh   5B06h, 5B07h         Dedicated DMA channels are supported.
                                      But the DMA channel specified is not
                                      supported.



          Cross Reference Tables                                        197





          Table A-2.  Status and Function Code Cross Reference (continued)
          ----------------------------------------------------------------

          Status      Function                   Description

          ----------------------------------------------------------------

           A0h   5401h                No corresponding handle value could
                                      be found for the handle name speci-
                                      fied.

           A1h   5301h, 5401h         A handle with this name already
                                      exists.  The specified handle was not
                                      assigned a name.

           A2h   5700h, 5701h         An attempt was made to "wrap around"
                                      the 1M-byte address space during the
                                      move/exchange.  The source starting
                                      address together with the length of
                                      the region to be moved/exchanged
                                      exceeds 1M bytes.  No data was
                                      moved/exchanged.

           A3h   4E01h, 4E02h         The contents of the data structure
                 4F00h, 4F01h         passed to the function have either
                 5B01h                been corrupted or are meaningless.

           A4h   5900h, 5B00h         The operating system has denied
                 5B01h, 5B02h         access to this function.  The
                 5B03h, 5B04h         function cannot be used at this time.
                 5B05h, 5B06h
                 5B07h, 5B08h
                 5D00h, 5D01h
                 5D02h

          ----------------------------------------------------------------

















          Cross Reference Tables                                        198





          Appendix B
          TESTING FOR THE PRESENCE OF THE EXPANDED MEMORY MANAGER



               Before an application program can use the Expanded Memory
               Manager, it must determine whether DOS has loaded the
               manager.  This appendix describes two methods your program
               can use to test for the presence of the memory manager and
               how to choose the correct one for your situation.

               The first method uses the DOS "open handle" technique; the
               second method uses the DOS "get interrupt vector" technique.


          Which method should your program use?

               The majority of application programs can use either the
               "open handle" or the "get interrupt vector" method.
               However, if your program is a device driver or if it
               interrupts DOS during file system operations, you must use
               only the "get interrupt vector" method.

               Device drivers execute from within DOS and can't access the
               DOS file system; programs that interrupt DOS during file
               system operations have a similar restriction.  During their
               interrupt processing procedures, they can't access the DOS
               file system because another program may be using the system.
               Since the "get interrupt vector" method doesn't require the
               DOS file system, you must use it for these types of pro-
               grams.


          The "open handle" technique

               Most application programs can use the DOS "open handle"
               technique to test for the presence of the memory manager.
               This section describes how to use the technique and gives an
               example.

          Caution.........................................................
               Don't use this technique if your program is a device driver
               or if it interrupts DOS during file system operations.  Use
               the "get interrupt vector" technique described later in this
               appendix.


          Using the "open handle" technique

               This section describes how to use the DOS "open handle"
               technique to test for the presence of the memory manager.
               Follow these steps in order:

          Testing For The Presence Of The EMM                           199





               1.  Issue an "open handle" command (DOS function 3Dh) in
                   "read only" access mode (register AL = 0).  This
                   function requires your program to point to an ASCII
                   string which contains the path name of the file or
                   device in which you're interested (register set DS:DX
                   contains the pointer).  In this case the file is
                   actually the name of the memory manager.

                   You should format the ASCII string as follows:

                   ASCII_device_name  DB  'EMMXXXX0', 0

                   The ASCII codes for the capital letters EMMXXXX0 are
                   terminated by a byte containing a value of zero.

               2.  If DOS returns no error status code, skip Steps 3 and 4
                   and go to Step 5.  If DOS returns a "Too many open
                   files" error status code, go to Step 3.  If DOS returns
                   a "File/Path not found" error status code, skip Step 3
                   and go to Step 4.

               3.  If DOS returns a "Too many open files" (not enough
                   handles) status code, your program should invoke the
                   "open file" command before it opens any other files.
                   This will guarantee that at least one file handle will
                   be available to perform the function without causing
                   this error.

                   After the program performs the "open file" command, it
                   should perform the test described in Step 6 and close
                   the "file handle" (DOS function 3Eh).  Don't keep the
                   manager "open" after this status test is performed since
                   "manager" functions are not available through DOS.  Go
                   to Step 6.

               4.  If DOS returns a "File/Path not found," the memory
                   manager is not installed.  If your application requires
                   the memory manager, the user will have to reboot the
                   system with a disk containing the memory manager and the
                   appropriate CONFIG.SYS file before proceeding.

               5.  If DOS doesn't return an error status code you can
                   assume that either a device with the name EMMXXXX0 is
                   resident in the system, or a file with this name is on
                   disk in the current disk drive.  Go to Step 6.

               6.  Issue an "I/O Control for Devices" command (DOS function
                   44h) with a "get device information" command (register
                   AL = 0).  DOS function 44h determines whether EMMXXXX0
                   is a device or a file.



          Testing For The Presence Of The EMM                           200





                   You must use the file handle (register BX) which you
                   obtained in Step 1 to access the "EMM" device.

                   This function returns the "device information" in a word
                   (register DX).  Go to Step 7.

               7.  If DOS returns any error status code, you should assume
                   that the memory manager device driver is not installed.
                   If your application requires the memory manager, the
                   user will have to reboot the system with a disk contain-
                   ing the memory manager and the appropriate CONFIG.SYS
                   file before proceeding.

               8.  If DOS didn't return an error status, test the contents
                   of bit 7 (counting from 0) of the "device information"
                   word (register DX) the function returned.  Go to Step 9.

               9.  If bit 7 of the "device information" word contains a
                   zero, then EMMXXXX0 is a file, and the memory manager
                   device driver is not present.  If your application
                   requires the memory manager, the user will have to
                   reboot the system with a disk containing the memory
                   manager and the appropriate CONFIG.SYS file before
                   proceeding.

                   If bit 7 contains a one, then EMMXXXX0 is a device.  Go
                   to Step 10.

               10. Issue an "I/O Control for Devices" command (DOS function
                   44h) with a "get output status" command (register AL =
                   7).

                   You must use the file handle you obtained in Step 1 to
                   access the "EMM" device (register BX).  Go to Step 11.

               11. If the expanded memory device driver is "ready," the
                   memory manager passes a status value of "FFh" in
                   register AL.  The status value is "00h" if the device
                   driver is "not ready."

                   If the memory manager device driver is "not ready" and
                   your application requires its presence, the user will
                   have to reboot the system with a disk containing the
                   memory manager and the appropriate CONFIG.SYS file
                   before proceeding.

                   If the memory manager device driver is "ready," go to
                   Step 12.





          Testing For The Presence Of The EMM                           201





               12. Issue a "Close File Handle" command (DOS function 3Eh)
                   to close the expanded memory device driver.  You must
                   use the file handle you obtained in Step 1 to close the
                   "EMM" device (register BX).

















































          Testing For The Presence Of The EMM                           202





          An example of the "open handle" technique

               The following procedure is an example of the "open handle"
               technique outlined in the previous section.

          ;--------------------------------------------------------------;
          ;    The following procedure tests for the presence of the     ;
          ;    EMM in the system.  It returns the CARRY FLAG SET if      ;
          ;    the EMM is present.  If the EMM is not present, this      ;
          ;    procedure returns the CARRY FLAG CLEAR.                   ;
          ;--------------------------------------------------------------;

          first_test_for_EMM  PROC  NEAR
          PUSH  DS
          PUSH  CS
          POP   DS
          MOV   AX,3D00h                       ; issue "device open" in
          LEA   DX,ASCII_device_name           ; "read only" mode
          INT   21h
          JC    first_test_for_EMM_error_exit  ; test for error
                                               ; during "device open"
          MOV   BX,AX                          ; get the "file
                                               ; handle" returned by DOS
          MOV   AX,4400h                       ; issue "IOCTL
          INT   21h                            ; get device info"
          JC    first_test_for_EMM_error_exit  ; test for error
                                               ; during "get device info"
          TEST  DX,0080h                       ; test to determine
          JZ    first_test_for_EMM_error_exit  ; ASCII_device_name
                                               ; is a device or a file
          MOV   AX,4407h                       ; issue "IOCTL"
          INT   21h
          JC    first_test_for_EMM_error_exit  ; test for error
                                               ; during "IOCTL"
          PUSH  AX                             ; save "IOCTL" status
          MOV   AH,3Eh                         ; issue "close
          INT   21h                            ; file handle"
          POP   AX                             ; restore "IOCTL" status
          CMP   AL,0FFh                        ; test for "device
          JNE   first_test_for_EMM_error_exit  ; ready" status
                                               ; returned by the driver
          first_test_for_EMM_exit:
          POP   DS                             ; EMM is present
          STC                                  ; in the system
          RET

          first_test_for_EMM_error_exit:
          POP   DS                             ; EMM is NOT present
          CLC                                  ; in the system
          RET
          ASCII_device_name   DB  'EMMXXXX0', 0
          first_test_for_EMM  ENDP

          Testing For The Presence Of The EMM                           203





          The "get interrupt vector" technique

               Any type of program can use the DOS "get interrupt vector"
               technique to test for the presence of the memory manager.
               This section describes how to use the technique and gives an
               example.

          Caution.........................................................
               Be sure to use this technique (and not the "open handle"
               technique) if your program is a device driver or if it
               interrupts DOS during file system operations.


          Using the "get interrupt vector" technique

               This section describes how to use the DOS "get interrupt
               vector" technique to test for the presence of the memory
               manager.  Follow these steps in order:

               1.  Issue a "get vector" command (DOS function 35h) to
                   obtain the contents of interrupt vector array entry
                   number 67h (addresses 0000:019Ch thru 0000:019Fh).

                   The memory manager uses this interrupt vector to perform
                   all manager functions.  The offset portion of this
                   interrupt service routine address is stored in the word
                   located at address 0000:019Ch; the segment portion is
                   stored in the word located at address 0000:019Eh.

               2.  Compare the "device name field" with the contents of the
                   ASCII string which starts at the address specified by
                   the segment portion of the contents of interrupt vector
                   address 67h and a fixed offset of 000Ah.  If DOS loaded
                   the memory manager at boot time this name field will
                   have the name of the device in it.

                   Since the memory manager is implemented as a character
                   device driver, its program origin is 0000h.  Device
                   drivers are required to have a "device header" located
                   at the program origin.  Within the "device header" is an
                   8 byte "device name field."  For a character mode device
                   driver this name field is always located at offset 000Ah
                   within the device header.  The device name field
                   contains the name of the device which DOS uses when it
                   references the device.

                   If the result of the "string compare" in this technique
                   is positive, the memory manager is present.





          Testing For The Presence Of The EMM                           204





          An example of the "get interrupt vector" technique

               The following procedure is an example of the "get interrupt
               vector" technique outlined in the previous section.


          ;--------------------------------------------------------------;
          ;    The following procedure tests for the presence of the     ;
          ;    EMM in the system.  It returns the CARRY FLAG SET if      ;
          ;    the EMM is present.  If the EMM is not present, this      ;
          ;    procedure returns the CARRY FLAG CLEAR.                   ;
          ;--------------------------------------------------------------;


          second_test_for_EMM  PROC  NEAR
          PUSH  DS
          PUSH  CS
          POP   DS
          MOV   AX,3567h                       ; issue "get interrupt
                                               ; vector"
          INT   21h
          MOV   DI,000Ah                       ; use the segment in ES
                                               ; returned by DOS, place
                                               ; the "device name field"
                                               ; OFFSET in DI
          LEA   SI,ASCII_device_name           ; place the OFFSET of the
                                               ; device name string in SI,
                                               ; the SEGMENT is already
                                               ; in DS
          MOV   CX,8                           ; compare the name strings
          CLD
          REPE  CMPSB
          JNE   second_test_for_EMM_error_exit

          second_test_for_EMM_exit:
          POP   DS                             ; EMM is present in
          STC                                  ; the system
          RET

          second_test_for_EMM_error_exit:
          POP   DS                             ; EMM is NOT present
          CLC                                  ; in the system
          RET

          ASCII_device_name   DB  'EMMXXXX0'
          second_test_for_EMM ENDP







          Testing For The Presence Of The EMM                           205





          Appendix C
          EXPANDED MEMORY MANAGER IMPLEMENTATION GUIDELINES



               In addition to the functional specification, the expanded
               memory manager should provide certain resources.  The
               following guidelines are provided so required resources are
               present in expanded memory managers which comply with this
               version of the LIM specification.

               o   The amount of expanded memory supported:
                   Up to a maximum of 32M bytes of expanded memory should
                   be supported.

               o   The number of handles supported:
                   The maximum number of expanded memory handles provided
                   should be 255, the minimum should be 64.

               o   Handle Numbering:
                   Although a handle is a word quantity, there is a maximum
                   of 255 handles, including the operating system handle.
                   This specification defines the handle word as follows:
                   the low byte of the word is the actual handle value, the
                   high byte of the handle is set to 00h by the memory
                   manager.  Previous versions of this specification did
                   not specify the value of handles.

               o   New handle type:  Handles versus Raw Handles:
                   The difference between a raw handle and a regular handle
                   is slight.  If you use Function 27 to "Allocate raw
                   pages to a handle," what is returned in DX is termed a
                   raw handle.  The raw handle does not necessarily refer
                   to 16K-byte pages.  Instead it refers to the "raw" page
                   size, which depends on the expanded memory hardware.

                   An application program can use Function 26 to find the
                   raw page size, and by using the raw handle Function 27
                   returns, it can access them with the finer resolution
                   that a particular expanded memory board may allow.

                   On the other hand, applications which use Function 4 to
                   "allocate pages to handle" receive a handle which always
                   refers to 16K-byte pages.  On expanded memory boards
                   with smaller raw pages, the EMM driver will allocate and
                   maintain the number of raw pages it takes to create a
                   single composite 16K-byte page.  The difference between
                   the expanded memory boards' raw page size and the 16K-
                   byte LIM page size is transparent to the application
                   when it is using a handle obtained with Function 4.



          EMM Implementation Guidelines                                 206





                   The memory manager must differentiate between pages
                   allocated to handles and pages allocated to raw handles.
                   The meaning of a call to the driver changes depending on
                   whether a handle or a raw handle is passed to the memory
                   manager.  If, for example, a handle is passed to
                   Function 18 (Reallocate), the memory manager will
                   increase or decrease the number of 16K-byte pages
                   allocated to the handle.  If Function 18 is passed a raw
                   handle, the memory manager will increase or decrease the
                   number of raw (non-16K-byte) pages allocated to the raw
                   handle.  For LIM standard boards, there is no difference
                   between pages and raw pages.

               o   The system Raw Handle (Raw Handle = 0000h):
                   For expanded memory boards that can remap the memory in
                   the lower 640K-byte address space, managing the pages of
                   memory which are used to fill in the lower 640K can be a
                   problem.  To solve this problem, the memory manager will
                   create a raw handle with a value of 0000h when DOS loads
                   the manager.  This raw handle is called the system
                   handle.

                   At power up, the memory manager will allocate all of the
                   pages that are mapped into the lower 640K bytes to the
                   system handle.  These pages should be mapped in their
                   logical order.  For example, if the system board
                   supplies 256K bytes of RAM, and the 384K bytes above it
                   is mappable, the system handle should have its logical
                   page zero mapped into the first physical page at 256K,
                   its logical page one mapped into the next physical page,
                   and so on.

                   The system handle should deal with raw pages.  To
                   release some of these pages so application programs can
                   use them, an operating system could decrease the number
                   of pages allocated to the system handle with the
                   "Reallocate" function.  Invoking the "Deallocate"
                   function would decrease the system handle to zero size,
                   but it must not deallocate the raw handle itself.  The
                   "Deallocate" function treats the system handle dif-
                   ferently than it treats other raw handles.  If the
                   operating system can ever be "exited" (for example, the
                   way Windows can be exited), it must increase the size of
                   the system handle back to what is needed to fill 640K
                   and map these logical pages back into physical memory
                   before returning to DOS.







          EMM Implementation Guidelines                                 207





                   There are two functional special cases for this handle:

                   -   The first special case deals with Function 4
                       (Allocate Pages).  This function must never return
                       zero as a handle value.  Applications must always
                       invoke Function 4 to allocate pages and obtain a
                       handle which identifies its pages.  Since Function 4
                       will never return a handle value of zero, an
                       application will never gain access to this special
                       handle.

                   -   The second special case deals with Function 6
                       (Deallocate Pages).  If the operating system uses
                       Function 6 to deallocate the pages which are
                       allocated to the system handle, the pages will be
                       returned to the manager for use, but the handle will
                       not be available for reassignment.  The manager
                       should treat a "deallocate pages" function request
                       for this handle the same as a "reallocate pages"
                       function request, where the number of pages to
                       reallocate to this handle is zero.

               o   Terminate and Stay Resident (TSR) Program Cooperation:
                   In order for TSR's to cooperate with each other and with
                   other applications, TSR's must follow this rule:  a
                   program may only remap the DOS partition it lives in.
                   This rule applies at all times, even when no expanded
                   memory is present.

               o   Accelerator Cards:
                   To support generic accelerator cards, the support of
                   Function 34, as defined by AST, is encouraged.





















          EMM Implementation Guidelines                                 208





          Appendix D
          OPERATING SYSTEM/ENVIRONMENT USE OF FUNCTION 28



               All expanded memory boards have a set of registers that
               "remember" the logical to physical page mappings.  Some
               boards have extra (or alternate) sets of these mapping
               registers.  Because no expanded memory board can supply an
               infinite number of alternate map register sets, this
               specification provides a way to simulate them using Function
               28 (Alternate Map Register Set).


          Examples

               For the examples in this section, assume the hardware
               supports alternate map register sets.  First Windows is
               brought up, then "Reversi" is started.  Then control is
               switched back to the MS-DOS Executive.  For this procedure,
               here are the calls to the expanded memory manager:

                                      Example 1

          Allocate alt reg set           ; Start up the MS-DOS
          (for MS-DOS Executive)         ; Executive

          Set alt reg set
          (for MS-DOS Executive)

          Allocate alt reg set           ; Start up Reversi
          (for Reversi)

          Set alt reg set
          (for Reversi)

          Map pages
          (for Reversi)

          Set alt ret set                ; Switch back to MS-DOS
          (for MS-DOS Executive)         ; Executive












          Operating System Use Of Function 28                           209





               Notice this procedure needed no "get" calls because the
               register set contained all the information needed to save a
               context.  However, using "Get" calls would have no ill
               effects.

                                      Example 2

          Allocate alt reg set           ; Start up MS-DOS
          (for MS-DOS Executive)         ; Executive

          Set alt reg set
          (for MS-DOS Executive)

          Get alt reg set
          (for MS-DOS Executive)

          Allocate alt reg set           ; Start up Reversi
          (for Reversi)

          Set alt reg set
          (for Reversi)

          Map pages
          (for Reversi)

          Get alt reg set
          (for Reversi)

          Set alt reg set                ; Switch back to MS-DOS
          (for MS-DOS Executive)         ; Executive

               The important point to follow is that a Set must always
               precede a Get.  The model of Set then Get is the inverse of
               what interrupt handlers use, which is Get then Set (Get the
               old map context and Set the new one).  Another crucial point
               is that an alternate map register set must have the current
               mapping when allocated; otherwise, the Set will create
               chaos.

               What happens if this is simulated in software?  The same Set
               and Get model applies.  The main difference is where the
               context is saved.











          Operating System Use Of Function 28                           210





               Since the allocate call is dynamic and there is no limit on
               the number of sets allocated, the OS/E must supply the space
               required.  Device drivers cannot allocate space dynamically,
               since the request would fail.  If the Allocate register set
               call returns a status indicating the alternate map register
               sets aren't supported, the OS/E must allocate space for the
               context.  It must also initialize the context using Function
               15.  At that point it can do the Set, passing a pointer to
               the map context space.  On the Get call, the EMM driver is
               to return a pointer to the same context space.

                                      Example 3

          Allocate alt reg set           ; Start up MS-DOS
          (for MS-DOS Executive)         ; Executive

          Get Page Map
          (for MS-DOS Executive)

          Set alt reg set
          (for MS-DOS Executive)

          Allocate alt reg set           ; Start up Reversi
          (for Reversi)

          Set alt reg set
          (for Reversi)

          Map pages
          (for Reversi)

          Get Page Map
          (for Reversi)

          Set alt ret set                ; Switch back to MS-DOS
          (for MS-DOS Executive)         ; Executive

















          Operating System Use Of Function 28                           211





          GLOSSARY



               The following terms are used frequently in this specifica-
               tion:


          Allocate                 To reserve a specified amount of
                                   expanded memory pages.

          Application Program      An application program is the program
                                   you write and your customer uses.  Some
                                   categories of application software are
                                   word processors, database managers,
                                   spreadsheet managers, and project
                                   managers.

          Conventional memory      The memory between 0 and 640K bytes,
                                   address range 00000h thru 9FFFFh.

          Deallocate               To return previously allocated expanded
                                   memory to the memory manager.

          EMM                      See Expanded Memory Manager.

          Expanded memory          Expanded memory is memory outside DOS's
                                   640K-byte limit (usually in the range of
                                   C0000h thru EFFFFh).

          Expanded Memory          A device driver that controls the
            Manager (EMM)          interface between DOS application
                                   programs and expanded memory.

          Extended memory          The 15M-byte address range between
                                   100000h thru FFFFFFh available on an
                                   80286 processor when it is operating in
                                   protected virtual address mode.

          Handle                   A value that the EMM assigns and uses to
                                   identify a block of memory requested by
                                   an application program.  All allocated
                                   logical pages are associated with a
                                   particular handle.

          Logical Page             The EMM allocates expanded memory in
                                   units (typically 16K bytes) called
                                   logical pages.

          Mappable Segment         A 16K-byte region of memory which can
                                   have a logical page mapped at it.


          Glossary                                                      212





          Map Registers            The set of registers containing the
                                   current mapping context of the EMM
                                   hardware.

          Mapping                  The process of making a logical page of
                                   memory appear at a physical page.

          Mapping Context          The contents of the mapping registers at
                                   a specific instant.  This context
                                   represents a map state.

          Page Frame               A collection of 16K-byte contiguous
                                   physical pages from which an application
                                   program accesses expanded memory.

          Page Frame               A page frame base address is the
            Base Address           location (in segment format) of the
                                   first byte of the page frame.

          Physical Page            A physical page is the range of memory
                                   addresses occupied by a single 16K-byte
                                   page.

          Raw Page                 The smallest unit of mappable memory
                                   that an expanded memory board can
                                   supply.

          Resident Application     A resident application program is loaded
            Program                by DOS, executes, and remains resident
                                   in the system after it returns control
                                   to DOS.  This type of program occupies
                                   memory and is usually invoked by the
                                   operating system, an application
                                   program, or the hardware.  Some example
                                   of resident application programs are RAM
                                   disks, print spoolers, and "pop-up"
                                   desktop programs.

          Status code              A code that an EMM function returns
                                   which indicates something about the
                                   result of running the function.  Some
                                   status codes indicate whether the
                                   function worked correctly and others may
                                   tell you something about the expanded
                                   memory hardware or software.








          Glossary                                                      213





          Transient Application    A transient application program is
            Program                loaded by DOS, executes, and doesn't
                                   remain in the system after it returns
                                   control to DOS.  After a transient
                                   application program returns control to
                                   DOS, the memory it used is available for
                                   other programs.

          Unmap                    To make a logical page inaccessible for
                                   reading or writing.











































          Glossary                                                      214





          INDEX



               Allocate Alternate Map Register Set  36, 163
               Allocate DMA Register Set  36, 168, 190
               Allocate Pages  5, 14, 23, 30, 34, 42, 43, 47, 49, 144,
                   147, 148, 193, 206, 208
               Allocate Raw Pages  36, 46, 80, 89, 147-149, 190, 193,
                   206
               Allocate Standard Pages  36, 42, 46, 80, 89, 144, 145,
                   147, 190, 193
               Alter Page Map & Call  7, 10, 35, 113, 118, 189
               Alter Page Map & Jump  7, 10, 35, 109, 189
               Alternate Map  10, 36, 151, 153-155, 157-159, 161, 163,
                   164, 165-168, 170, 173, 175, 179, 182, 190, 197,
                   209, 210, 211
               Alternate Map Register Set  10, 36, 151, 153-155, 157,
                   158, 159, 161, 163-168, 170, 173, 175, 190, 197,
                   209, 210
               Alternate Mapping and Unmapping Methods  81
               Alternate Register  139, 166, 173, 177
               Data Aliasing  12
               Deallocate Alternate Map Register Set  36, 166
               Deallocate DMA Register Set  36, 175, 190
               Deallocate Pages  5, 14, 25, 31, 34, 43, 49, 88, 145,
                   148, 208
               Design Considerations  91, 151
               Device Driver  1, 15, 43, 53, 55, 144, 148, 199, 201,
                   202, 204, 212
               Disable DMA on Alternate Map Register Set  173
               Disable OS/E Function Set  36, 179, 180, 182, 185
               DMA  36, 138-140, 151, 152, 168-176, 190, 197
               DMA Channels  139, 171, 173, 174, 197
               DMA Register  36, 139, 140, 151, 152, 168-171, 173-176,
                   190, 197
               DOS  1, 12, 14, 15, 19, 21, 30, 31, 49, 53, 88, 199-205,
                   207-214
               Enable DMA on Alternate Map Register Set  170
               Enable OS/E Function Set  36, 179, 180
               Enable/Disable OS/E Function Set  179, 180, 182, 185
               Exchange Memory Region  7, 10, 35, 120, 126, 127, 189
               Expanded Memory Support of DMA  151
               Expanded Memory Support of DMA Register Sets  151
               Extended Memory  91
               Function 1  37
               Function 10  57
               Function 11  58
               Function 12  59
               Function 13  61
               Function 14  7, 63


          Index                                                         215





               Function 15  13, 53, 55, 65, 67, 69, 71, 73, 76, 139,
                   153, 154, 155, 158, 211
               Function 16  13, 73, 76, 78
               Function 17  6, 80, 82, 85
               Function 18  6, 43, 88, 144, 148, 207
               Function 19  7, 91, 92, 94, 96
               Function 2  4, 38
               Function 20  7, 98, 100
               Function 21  7, 42, 102, 105, 107
               Function 22  109
               Function 23  113, 118
               Function 24  7, 120, 126
               Function 25  6, 8, 46, 74, 85, 132, 136
               Function 26  138, 142, 179, 182, 206
               Function 27  42, 46, 80, 89, 144, 145, 147-149, 193, 206
               Function 28  140, 151, 153, 157, 161, 163, 164, 166,
                   168, 170, 173, 175, 179, 182, 209
               Function 29  177
               Function 3  4, 40, 142
               Function 30  138, 151, 153, 157, 161, 163, 166, 168,
                   170, 173, 175, 179, 182, 185
               Function 4  4, 42, 43, 46, 47, 49, 80, 89, 144, 145,
                   147, 149, 193, 206, 208
               Function 5  4, 46, 81
               Function 6  4, 43, 49, 88, 145, 148, 208
               Function 7  5, 51
               Function 8  46, 50, 53, 55
               Function 9  46, 50, 53, 55
               Get & Set Page Map  35, 69
               Get All Handle Pages  9, 34, 63
               Get Alternate Map Register Set  36, 153, 154, 157, 190
               Get Alternate Map Save Array Size  36, 161, 190
               Get Attribute Capability  7, 96
               Get Expanded Memory Hardware Information  10, 138, 142,
                   179, 182
               Get Handle Attribute  35, 92
               Get Handle Count  9, 34, 59
               Get Handle Directory  10, 35, 102, 105, 107
               Get Handle Name  35, 98
               Get Handle Pages  7, 9, 34, 61
               Get Hardware Configuration Array  36, 138
               Get Interrupt Vector  15, 21, 30, 199, 204, 205
               Get Mappable Physical Address Array  6, 8, 10, 35, 46,
                   85, 132, 136
               Get Mappable Physical Address Array Entries  8, 136
               Get Page Frame Address  5, 34, 38
               Get Page Map  35, 65, 118, 153-155, 158, 211
               Get Page Map Stack Space Size  35, 118
               Get Partial Page Map  35, 73, 78
               Get Size of Page Map Save Array  35, 65, 67, 71, 139
               Get Size of Partial Page Map Save Array  74, 76, 78
               Get Status  5, 34, 37

          Index                                                         216





               Get Total Handles  35, 107
               Get Unallocated Page Count  5, 22, 34, 40, 142
               Get Unallocated Raw Page Count  36, 142, 189
               Get Version  5, 34, 51
               Get/Set Handle Attribute  9, 91, 92, 94, 96
               Get/Set Handle Name  10, 98, 100
               Get/Set Page Map  9, 13, 65, 67, 69, 71
               Get/Set Partial Page Map  9, 13, 73, 76, 78
               Handle Attribute  9, 35, 91-94, 96, 188
               Handle Name  6, 7, 10, 35, 98, 100, 105, 106, 188, 198
               Intel  i, ii, 1, 5, 57, 58
               Interrupt Vector  12, 15, 21, 30, 199, 204, 205
               LIM  1, 7, 13, 19, 27, 53, 55, 138, 140, 206, 207
               Logical Page  1, 5, 12, 16, 19, 23, 28, 31, 32, 46-48,
                   80-83, 85, 86, 88, 110, 111, 115, 116, 120, 122,
                   123, 125, 126, 128, 129, 131, 147, 194, 196, 207,
                   212-214
               Logical Page/Physical Page Method  82
               Logical Page/Segment Address Method  85
               Lotus  i, ii, 1, 5, 57, 58
               Map Register  10, 13, 36, 53, 55, 151, 153-155, 157-159,
                   161, 163-168, 170, 173, 175, 179, 182, 190, 197,
                   209-211
               Map/Unmap Handle Pages  46
               Map/Unmap Multiple Handle Pages  9, 35, 80, 82, 85
               Mapping and Unmapping Multiple Pages Simultaneously  80
               Mapping Multiple Pages  6, 80
               Microsoft  i, ii, 1, 5, 14, 30, 42, 57, 58, 144, 148
               Move Memory Region  35, 120, 121, 189
               Move/Exchange Memory Region  7, 10, 120, 126
               Open Handle  64, 102, 199, 200, 203, 204
               Operating System  3, 8, 10-12, 42, 43, 59, 63, 107, 138,
                   139, 141, 142, 144-151, 153-159, 161-163, 165-171,
                   173-177, 179-183, 185, 186, 190, 191, 198, 206,
                   207-209, 213
               Page Frame  1-6, 14, 17-19, 24, 28, 31, 34, 38, 39, 47,
                   53, 55, 121, 128, 133, 187, 213
               Page Map  7, 9, 10, 13, 34, 35, 50, 53, 55, 65, 67, 69,
                   71, 73-76, 78, 109, 113, 118, 139, 153-155, 158,
                   187, 188, 189, 211
               Page Mapping Register I/O Array  57
               Page Translation Array  58
               Physical Page  1, 5, 6, 8, 10, 12, 16, 23, 28, 31, 35,
                   46, 47, 48, 80-83, 85, 109-112, 114-117, 132-134,
                   136, 138, 139, 142, 147, 188, 194, 207, 209, 213
               Prepare Expanded Memory Hardware For Warm Boot  10, 177
               Raw Handle  147, 149, 150, 206, 207
               Raw Page  36, 142, 143, 147, 189, 206
               Reallocate Pages  9, 35, 43, 88, 144, 145, 148, 208
               Restore Page Map  9, 13, 34, 50, 53, 55
               Return Access Key  185
               Save Page Map  9, 13, 34, 50, 53, 55

          Index                                                         217





               Search For Named Handle  7, 35, 105
               Set Alternate Map Register Set  36, 153-155, 157, 158,
                   163, 190
               Set Handle Attribute  9, 35, 91, 92, 94, 96
               Set Handle Name  7, 10, 35, 98, 100
               Set Page Map  9, 13, 35, 65, 67, 69, 71, 188
               Set Partial Page Map  9, 13, 35, 73, 76, 78
               Standard Handle  146
               Standard Page  147
               System DMA Capabilities  151
               TSR  12, 13, 208
               Unmapping Multiple Pages  6, 80









































          Index                                                         218

 M╡pALLINFO.TXT
Following are BBSes that are members of DV-NET.  DV-Net is an informal
network of BBS's that carry files that would be useful to DESQview users.
Not all BBSes that carry the DESQview conference are members of DV-Net.

All address are NetMail addresses.

            ----------------------------------------------
                 DVNet DESQview Support File Network
            ----------------------------------------------
         DESQview is a trademark of Quarterdeck Office Systems
       -----------------------------------------------------------
         DVNet is not affiliated with Quarterdeck Office Systems
   ----------------------------------------------------------------

   Name, City and State             NetAddress  Telephone     Maxbaud
   -------------------------------  ---------- ------------  -------
 *65'North, Fairbanks, AK         1:17/38    907-452-1460  9600HSTV32
  Opus 386, Davis, CA             1:203/910  916-753-6321  2400
  Carl's Corner, San Jose, CA     1:10/1     408-248-9704  9600HSTV32
  Carl's Corner, San Jose, CA     1:10/2     408-248-0198  2400
  SeaHunt BBS, Burlingame, CA     1:125/20   415-344-4348  9600HST
  Stingray!, Clovis CA            1:205/12   209-298-9461  9600HST
  SF PCUG BBS, San Francisco CA   1:1/310    415-621-2609  9600HSTV32RE
  Bink of an Aye, Portland, OR    1:105/42   503-297-9043  9600PEPV32MO
  P C Support, Portland, OR       1:105/66   503-297-9078  2400
  Atarian BBS, Portland, OR       1:105/10   503-245-9730  9600HSTV32
  Busker's BoneYard, Portland,OR  1:105/14   503-771-4773  9600PEP
  Busker's Boneyard, Portland,OR  1:105/41   503-775-7926  9600HSTV32
  Pacifier BBS, Vancouver, WA     1:105/103  206-253-9770  9600HSTV32
  Puget Sound Gtwy., Puyallup, WA 1:138/3    206-566-8854  9600HST
  Rampart General,Kansas City,MO  1:280/6    816-761-4039  9600HST
  Oregon Trail XRoads, Casper WY  1:303/5    307-472-3615  9600H96
  Dawg Byte, Nashville, TN        1:116/29   615-385-4268  9600HST
  Dickson County, Dickson, TN     1:116/25   615-446-4475  2400
  Programmers' Attic, Will., MI   1:159/850  517-655-3347  2400
  Dark Side Of the Moon,Savoy IL  1:233/493  217-356-6922  9600HSTV32
  Ecclesia Place, Monroeville, PA 1:129/75   412-373-8612  9600HST
  The Other BBS, Harrisburg PA    1:270/101  717-657-2223  9600HST
  IBM Tech Fido, Pepperell, MA    1:322/1    508-433-8452  9600HSTV32
  Waystar BBS, Marlborough, MA    1:322/14   508-481-7147  9600HST
  Andromeda Galaxy, Troy NY       1:267/167  518-273-8313  9600HST
  Treasure Island, Danbury, CT    1:141/730  203-791-8532, 9600HST
  Addict's Attic,Germantown MD    1:109/423  301-428-8998  9600HST
  Maple Shade Opus,Maple Shade NJ 1:266/12   609-482-8604  9600HSTV32
  Capital City , Burlington NJ   99:9230/1   609-386-1989  9600HSTV32
  Capital City , Burlington NJ    8:950/10   609-386-1989  9600HSTV32
  Southern Cross BBS, Miami FL    1:135/69   305-220-8752  9600HST
  Software Designer, Albany, GA   1:3617/1   912-432-2440  9600HSTV32
  Software Designer, Albany, GA   8:928/1    912-432-2440  9600HSTV32
  Dragon's Lair, Galveston, TX    1:386/451  409-762-2761  9600HST
  Dragon's Lair, Galveston, TX    1:386/1451 409-762-7456  2400MNP
  Conch Opus, Houston, TX         1:106/357  713-667-7213  2400PCP
  Inns of Court, Dallas, TX       1:124/6101 214-458-2620  9600HSTV32
  Dallas Email, Dallas, TX        8:930/101  214-358-1205  9600HSTV32MO
  Spare Parts, Bedford, TX        1:130/38   817-540-3527  9600HST
  QE2, Austin TX                  1:382/58   512-328-1229  2400
  Ned's Opus HST Ottawa,ON Canada 1:163/211  613-523-8965  9600HST
  Ned's Opus, Ottawa ON Canada    1:163/210  613-731-8132  2400
  Imperial Terran, St Cath,ON     1:247/102  416-646-7105  9600HST
  Arcane BBS, Laval PQ Canada     1:167/116  514-687-9586  9600HST
  Zone 2 & Zone 3
  ------------------------------  ---------  ------------- -------
  The HEKOM Board (Netherlands)   2:286/3    31-3483-4072  2400MNP5
  BBS_D.C.V.V., Maaseik (Belgium) 2:295/26   32-11-568620